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)
source
VisualGeometryToolkitCore.JeffreysPrior — Method
JeffreysPrior() -> IGPrior

The 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.

source
VisualGeometryToolkitCore.fit_scale — Method
fit_scale(prior::IGPrior, rss, dof) -> s2

Fit 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.

source
VisualGeometryToolkitCore.partition_rss — Method
partition_rss(order, residuals, k) -> Float64

The 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).

source
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.

source
VisualGeometryToolkitCore.weighted_rss — Method
weighted_rss(w, sq_distances, n) -> Float64

The 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).

source
VisualGeometryToolkitCore.weighted_sq — Method
weighted_sq(w, sq_r) -> w·sq_r, exactly 0 at w = 0

One 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.

source
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.

  • s2 inlier variance sigma^2
  • nu effective dof: Inf is 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.
  • gamma the label prior Pr(z_i = 1); a general gamma adds log(gamma/(1-gamma)) to the boundary.
  • d_g the codimension, REQUIRED. It enters the outlier density as the EXPONENT (2·outlier_halfwidth)^-d_g, so no value of it is a safe default.
source
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.

source
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}(…).

source
VisualGeometryToolkitCore.decision_boundary — Method
decision_boundary(m::GauInlier, outlier_halfwidth) -> Float64

The 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.

source
VisualGeometryToolkitCore.decision_width — Method
decision_width(m::GauInlier, boundary) -> outlier_halfwidth

The 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.

source
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.

source
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.

source
VisualGeometryToolkitCore.next_nu — Method
next_nu(ν, sq_distances, s_hat_sq, w_fixed, n; d_g=1, kwargs...) -> ν_new

M-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.

source
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.

source
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.

source
VisualGeometryToolkitCore.posterior_weight — Method
posterior_weight(m::StudentTMixture, sq_r) -> w

The 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.

source
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.

source
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 ν → ∞.

source
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.

source
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.

source
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]).

source
VisualGeometryToolkitCore.PosteriorWeightState — Type
PosteriorWeightState

Mutable 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.

source
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.

source
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.

source
VisualGeometryToolkitCore.inlier_prior — Method
inlier_prior(pws::PosteriorWeightState) -> Float64

The mixing proportion π the E-step weighs with: the prior probability that a residual is an inlier (1/2 unless estimated or held elsewhere).

source
VisualGeometryToolkitCore.median_seeded_posterior — Method
median_seeded_posterior(sq, n; outlier_halfwidth, ν, prior, codimension = 2) -> PosteriorWeightState

A 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.

source
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.

source
VisualGeometryToolkitCore.mixture_nll — Method
mixture_nll(pws::PosteriorWeightState, r, n) -> Float64

The 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.

source
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.

source
VisualGeometryToolkitCore.reset_posterior! — Method
reset_posterior!(pws; ν, s_hat_sq, log_two_outlier_halfwidth, prior, codimension, inlier_prior) -> pws

PosteriorWeightState(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).

source
VisualGeometryToolkitCore.seed_posterior! — Method
seed_posterior!(pws, sq_distances, n, model_dof, k; order, prior, log_two_outlier_halfwidth,
                codimension = 1) -> pws

The 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.

source
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.

source
VisualGeometryToolkitCore.student_t_dof — Method
student_t_dof(pws::PosteriorWeightState) -> Float64

The Student-t degrees of freedom ν of the inlier density — not the model's DOF (minimal_sample_size), and not Distributions' dof.

source
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 π.

source
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 ν.

source
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 ŝ².

source
VisualGeometryToolkitCore.truncated_log_normaliser — Method
truncated_log_normaliser(shape, sq_loss_width, depth, r_max) -> Float64

log 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.

source

Block Coordinate Descent

VisualGeometryToolkitCore.AbstractBlockCoordinateMethod — Type
AbstractBlockCoordinateMethod

Abstract 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 seeds method.ws's residual buffers, which the iterations then read); the method is the mutated argument
  • update_model!(state, method, prob, θ) — the model block: one weighted update of θ (weighted least squares, LM, Newton), or θ unchanged; nothing when 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 own StoppingCriterion (default StopNever)
  • block_coordinate_result(state, method, prob, θ, stop_reason, final_iter, stop_rule) — package result
source
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.

source
VisualGeometryToolkitCore.StoppingCriterion — Type
StoppingCriterion

When 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.

source
VisualGeometryToolkitCore.block_coordinate_descent! — Method
block_coordinate_descent!(likelihood, method, prob, θ₀; max_iter) -> result

Block coordinate descent on a negative log-likelihood, over three blocks:

  • model — update_model! (the method): weighted least squares, LM, Newton, or nothing at all (a fixed-model method such as a seed EM, which returns θ unchanged);
  • nuisance — update_nuisance! (the likelihood): scale, mixing proportion, ν, Barron α, or nothing;
  • weights — update_weights! (the likelihood): 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.jlhere
AbstractManoptSolverStatethe 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_reasonStoppingCriterion, stop_reason (pure; the reason is returned)
StopAfterIteration, StopWhenAny (criteria or-ed)StopAfterIteration, StopWhenAny (criteria or-ed)
RecordSolverStateRecorded
get_solver_resultblock_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).

source
VisualGeometryToolkitCore.init_state! — Function
init_state!(method::AbstractBlockCoordinateMethod, prob, θ₀) -> state

Build 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.

source
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.

source
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.

source
VisualGeometryToolkitCore.step_solver! — Method
step_solver!(state, likelihood, method, prob, θ, iter) -> θ′ or nothing

One 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.

source
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.

source
VisualGeometryToolkitCore.stop_rule — Method
stop_rule(criterion::StoppingCriterion, method) -> StopRule

The 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.

source
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.

source
VisualGeometryToolkitCore.update_model! — Function
update_model!(state, method::AbstractBlockCoordinateMethod, prob, θ) -> θ′ | nothing

The 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.

source

Index