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
ReturnCodeWhy 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, isSuccess: 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.
VisualGeometryToolkitCore.ReturnCode.T — Type
ReturnCode.T: the ReturnCode enum type (SciMLBase's ReturnCode.T).
VisualGeometryToolkitCore.ReturnCode.Default — Constant
ReturnCode.Default: a ReturnCode — the solving process has not been run (SciMLBase's default). Not successful.
VisualGeometryToolkitCore.ReturnCode.Success — Constant
ReturnCode.Success: a ReturnCode — the solve succeeded (a tolerance or stop rule, a closed form, a RANSAC's confidence or every sample). Successful.
VisualGeometryToolkitCore.ReturnCode.Terminated — Constant
ReturnCode.Terminated: a ReturnCode — a callback (or LODR's lifted mixture leaving its basin) ended the solve. Successful, as in SciMLBase.
VisualGeometryToolkitCore.ReturnCode.MaxIters — Constant
ReturnCode.MaxIters: a ReturnCode — the iteration cap, or a RANSAC's trial budget, with no tolerance or confidence met. Not successful.
VisualGeometryToolkitCore.ReturnCode.InitialFailure — Constant
ReturnCode.InitialFailure: a ReturnCode — the start was unusable: too few data, a degenerate configuration, a non-finite start point. Not successful.
VisualGeometryToolkitCore.ReturnCode.Failure — Constant
ReturnCode.Failure: a ReturnCode — the solve failed otherwise (non-finite values, a failed model block, no RANSAC model). Not successful.
VisualGeometryToolkitCore.ReturnCode.MaxTime — Constant
ReturnCode.MaxTime: a ReturnCode — the time cap. Not successful.
VisualGeometryToolkitCore.ReturnCode.Stalled — Constant
ReturnCode.Stalled: a ReturnCode — an LM stopped at a point that fails the stationarity postcondition. Not successful.
VisualGeometryToolkitCore.ReturnCode.InternalLinearSolveFailed — Constant
ReturnCode.InternalLinearSolveFailed: a ReturnCode — a linear system inside the fit could not be solved. Not successful.
VisualGeometryToolkitCore.successful_retcode — Function
successful_retcode(code::ReturnCode.T) -> BoolWhether code is a success state — SciMLBase's rule over the values the stack defines: ReturnCode.Success and ReturnCode.Terminated. The one success test; converged reads it.
VisualGeometryToolkitCore.StopRule — Type
StopRuleWhich 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'sParameterChangeStop;NoImprovement— the EM'sNoImprovementStop(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 isFailure;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.
VisualGeometryToolkitCore.NoRule — Constant
NoRule: a StopRule — no rule fired: the run never iterated, or the host LM stopped after a cost disagreement.
VisualGeometryToolkitCore.ClosedForm — Constant
ClosedForm: a StopRule — a one-shot solve, or a selection among fixed candidates.
VisualGeometryToolkitCore.CostDecrease — Constant
CostDecrease: a StopRule — the cost decrease fell below its tolerance.
VisualGeometryToolkitCore.IncrementSize — Constant
IncrementSize: a StopRule — the update fell below its tolerance.
VisualGeometryToolkitCore.RejectionCap — Constant
RejectionCap: a StopRule — NLLSsolver's consecutive cost increases (maxfails).
VisualGeometryToolkitCore.ParameterChange — Constant
ParameterChange: a StopRule — the EM's ParameterChangeStop.
VisualGeometryToolkitCore.NoImprovement — Constant
NoImprovement: a StopRule — the EM's NoImprovementStop.
VisualGeometryToolkitCore.ExactFit — Constant
ExactFit: a StopRule — every residual is zero.
VisualGeometryToolkitCore.ToleranceMet — Constant
ToleranceMet: a StopRule — a search met its accuracy tolerance.
VisualGeometryToolkitCore.LadderConverged — Constant
LadderConverged: a StopRule — a graduated-non-convexity ladder converged.
VisualGeometryToolkitCore.LeftBasin — Constant
LeftBasin: a StopRule — the iterate left the seed's basin of attraction.
VisualGeometryToolkitCore.ShapeGate — Constant
ShapeGate: a StopRule — the fitted shape failed a validity gate (its code is Failure).
VisualGeometryToolkitCore.IterationCap — Constant
IterationCap: a StopRule — the iteration cap.
VisualGeometryToolkitCore.TimeCap — Constant
TimeCap: a StopRule — the time cap.
VisualGeometryToolkitCore.NonFinite — Constant
NonFinite: a StopRule — a non-finite cost, step or gradient, or a failed model block.
VisualGeometryToolkitCore.Callback — Constant
Callback: a StopRule — a user callback.
VisualGeometryToolkitCore.TrialBudget — Constant
TrialBudget: a StopRule — a RANSAC drew its whole trial budget.
VisualGeometryToolkitCore.AdaptiveCount — Constant
AdaptiveCount: a StopRule — a RANSAC drew its adaptive trial count (its confidence was reached).
VisualGeometryToolkitCore.SeedKept — Constant
SeedKept: a StopRule — a RANSAC's score guard kept the seed (the refined model scored below it).
VisualGeometryToolkitCore.stop_rule — Function
stop_rule(r::FitResult) -> StopRuleWhich rule ended the fit (StopRule), the detail behind its retcode.
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.found_model — Function
found_model(r::FitResult) -> BoolWhether 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.
VisualGeometryToolkitCore.retcode_symbol — Function
retcode_symbol(code::ReturnCode.T, rule::StopRule) -> Symbol
retcode_symbol(r::FitResult) -> SymbolThe 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.
retcode_symbol(r::FitResult) -> SymbolThe 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.
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:
retcode | ReturnCode | StopRule |
|---|---|---|
:converged | Success | rule |
:solved | Success | ClosedForm |
:stalled | Stalled | rule |
:max_iterations | MaxIters | IterationCap |
:max_time | MaxTime | TimeCap |
:solve_failed | Failure | NonFinite |
:degenerate | InitialFailure | NoRule |
:not_run | Default | NoRule |
:guard_kept_seed | Success | SeedKept |
:no_lo | Success | ClosedForm (read back as :solved) |
:thin_partition | InitialFailure | NoRule (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.
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).