Termination Record

Why a fit stopped is its termination record: the verdict, a ReturnCode (ReturnCode.T, SciMLBase's names and success rule), read by retcode, and the rule that fired, a StopRule, read by stop_rule. Both are in the result's core, so every producer records them. converged is strict, successful_retcode of the code: a cap or a stall is not converged. Whether a RANSAC found a model is found_model.

VisualGeometryToolkitCore.ReturnCode — Module
ReturnCode

Why a fit stopped: the standard verdict, modelled on SciMLBase.ReturnCode (SciMLBase 3.58; the Julia ecosystem's return-code interface). The enum type is ReturnCode.T and each value a module property (ReturnCode.Success), as with SciMLBase's EnumX enum; the names, integer values and success rule (successful_retcode) are SciMLBase's, so a later SciMLBase bridge is a reinterpretation. Only the values the stack produces are defined; their meaning is SciMLBase's:

  • ReturnCode.Default — the solving process has not been run (SciMLBase's default): a record of a solve that never ran, such as a RANSAC result's local-optimization record when no local optimization ran. Not successful.
  • ReturnCode.Success — the solve succeeded: a tolerance or stop rule ended an iteration (an LM's cost-decrease or step-size tolerance, converged by definition; its rejection cap once its stationarity postcondition holds), a closed-form solve, a RANSAC that reached its confidence or drew every sample. Successful.
  • ReturnCode.Terminated — a user callback ended the solve (NLLSsolver's callback flags). Successful, as in SciMLBase.
  • ReturnCode.MaxIters — the iteration cap was reached with no tolerance met on the last iteration; for a RANSAC, the trial budget was drawn without reaching the confidence. Not successful.
  • ReturnCode.MaxTime — the time cap. Not successful.
  • ReturnCode.Stalled — an LM stopped at a point that fails the stationarity postcondition: the host LM's consecutive-rejection cap (a tolerance stop, the cost decrease or the step size, is Success: Core 0.11.0's owner ruling), the device LM's (static_lm) stops short of its success rule. Not successful.
  • ReturnCode.InitialFailure — the start was unusable: too few data or a degenerate configuration before any iteration, or a non-finite cost or gradient at the start point. Not successful.
  • ReturnCode.InternalLinearSolveFailed — a linear system inside the fit (a weighted least-squares or normal-equation solve) could not be solved. Not successful.
  • ReturnCode.Failure — the solve failed otherwise: a non-finite cost, step or gradient during it, a failed model block, or a RANSAC that found no model. Not successful.

Compare with successful_retcode, never == ReturnCode.Success; the rule that fired is the result's stop_rule.

source
VisualGeometryToolkitCore.StopRule — Type
StopRule

Which rule ended a fit — the detail behind its ReturnCode (the verdict), read by stop_rule:

  • NoRule — no rule fired: a run that never iterated (a degenerate start, a non-finite start point), or a host-LM run NLLSsolver stopped after a cost disagreement with no tolerance met (nlls_termination, Core 0.11.1);
  • ClosedForm — a one-shot solve (no iteration), or a selection among fixed candidates;
  • CostDecrease — the cost decrease fell below its tolerance (NLLSsolver's relative or absolute cost stop; an IRLS outer loop's robust cost; an EM's negative log-likelihood under a held model);
  • IncrementSize — the update fell below its tolerance (NLLSsolver's step stop; an IRLS fit's parameter change);
  • RejectionCap — NLLSsolver's consecutive cost increases (maxfails);
  • ParameterChange — the EM's ParameterChangeStop;
  • NoImprovement — the EM's NoImprovementStop (the incumbent's cost did not fall);
  • ExactFit — every residual is zero;
  • ToleranceMet — a search met its accuracy tolerance (a spline spacing search);
  • LadderConverged — a graduated-non-convexity ladder converged (LODR);
  • LeftBasin — the iterate left the seed's basin of attraction (LODR);
  • ShapeGate — the fitted shape failed a validity gate (BlobBoards' blob fit: not a peak, or an aspect above its maximum); its code is Failure;
  • IterationCap — the iteration cap;
  • TimeCap — the time cap;
  • NonFinite — a non-finite cost, step or gradient, or a failed model block;
  • Callback — a user callback;
  • TrialBudget — a RANSAC drew its whole trial budget (the cap, or every sample of an exhaustive sampler);
  • AdaptiveCount — a RANSAC drew its adaptive trial count (its confidence was reached);
  • SeedKept — a RANSAC's score guard kept the seed: the refined model scored below it (recorded with the local optimization's own code).

An @enum (isbits): a metadata that carries it stays concretely typed.

source
VisualGeometryToolkitCore.stop_rule — Function
stop_rule(r::FitResult) -> StopRule

Which rule ended the fit (StopRule), the detail behind its retcode.

source
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.found_model — Function
found_model(r::FitResult) -> Bool

Whether the fit returned an estimate — a RANSAC's "a model was found" (estimate(r) !== nothing), whatever its retcode: a search that drew its whole trial budget without reaching its confidence still found one.

source
VisualGeometryToolkitCore.retcode_symbol — Function
retcode_symbol(code::ReturnCode.T, rule::StopRule) -> Symbol
retcode_symbol(r::FitResult) -> Symbol

The legacy Symbol spelling of a termination record (a log line, a persisted record that names the Symbol; retcode_symbol(r) of a result) — the one map from a record to a Symbol: Success is :solved for a ClosedForm rule and :converged otherwise; Terminated:converged; MaxIters:max_iterations; MaxTime:max_time; Stalled:stalled; InitialFailure:degenerate, or :solve_failed for a NonFinite start; InternalLinearSolveFailed:solve_failed; Failure:no_model when a RANSAC's trial rule ended it (TrialBudget, AdaptiveCount) and :solve_failed otherwise; Default (not run) :not_run, and any code with the SeedKept rule :guard_kept_seed.

source
retcode_symbol(r::FitResult) -> Symbol

The legacy Symbol spelling of the result's record, retcode_symbol(retcode(r), stop_rule(r)) (:converged, :solved, :max_iterations, :degenerate, :solve_failed, :stalled, :max_time, :no_model): for a log line or a persisted record that names the Symbol.

source
VisualGeometryToolkitCore.retcode_from_symbol — Function
retcode_from_symbol(retcode::Symbol, rule::StopRule) -> (ReturnCode.T, StopRule)

The termination record of a loop that reports a legacy Symbol — the inverse of retcode_symbol, so retcode_symbol(retcode_from_symbol(s, rule)...) === s. rule is the rule a SUCCESSFUL stop of that loop fired (its tolerance: CostDecrease, IncrementSize, ParameterChange, …), also the one whose postcondition a :stalled stop failed:

retcodeReturnCodeStopRule
:convergedSuccessrule
:solvedSuccessClosedForm
:stalledStalledrule
:max_iterationsMaxItersIterationCap
:max_timeMaxTimeTimeCap
:solve_failedFailureNonFinite
:degenerateInitialFailureNoRule
:not_runDefaultNoRule
:guard_kept_seedSuccessSeedKept
:no_loSuccessClosedForm (read back as :solved)
:thin_partitionInitialFailureNoRule (read back as :degenerate)

The last four are a RANSAC's former local-optimization statuses (its lo_retcode before it was a record). Any other Symbol (a RANSAC's :no_model) is an ArgumentError: its producer states its record itself.

source
VisualGeometryToolkitCore.worst_retcode — Function
worst_retcode(a::Tuple{ReturnCode.T, StopRule}, b::Tuple{ReturnCode.T, StopRule}, more...) -> Tuple{ReturnCode.T, StopRule}

The termination of a fit that ran several solves (stages, rounds, the cycles of an outer loop — its own cap counted as one), from each solve's (code, rule): the most severe code, in the order InitialFailure > InternalLinearSolveFailed > Failure > MaxTime > MaxIters > Stalled > Terminated > Success, with that solve's rule. On a tie the LATER solve's pair is kept (the final solve's rule is the informative one).

source