Add StalledSuccess and improve return code documentation

Author: ChrisRackauckas

Project.toml

@@ -1,7 +1,7 @@
 name = "SciMLBase"
 uuid = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 authors = ["Chris Rackauckas <[email protected]> and contributors"]
-version = "2.88.0"
+version = "2.89.0"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"

docs/src/interfaces/Solutions.md

@@ -82,14 +82,21 @@ SciMLBase.ReturnCode.Terminated
 SciMLBase.ReturnCode.DtNaN
 SciMLBase.ReturnCode.MaxIters
 SciMLBase.ReturnCode.MaxNumSub
+SciMLBase.ReturnCode.MaxTime
 SciMLBase.ReturnCode.DtLessThanMin
 SciMLBase.ReturnCode.Unstable
 SciMLBase.ReturnCode.InitialFailure
 SciMLBase.ReturnCode.ConvergenceFailure
 SciMLBase.ReturnCode.Failure
+SciMLBase.ReturnCode.Infeasible
 SciMLBase.ReturnCode.ExactSolutionLeft
 SciMLBase.ReturnCode.ExactSolutionRight
 SciMLBase.ReturnCode.FloatingPointLimit
+SciMLBase.ReturnCode.InternalLineSearchFailed
+SciMLBase.ReturnCode.InternalLinearSolveFailed
+SciMLBase.ReturnCode.ShrinkThresholdExceeded
+SciMLBase.ReturnCode.Stalled
+SciMLBase.ReturnCode.SuccessfulStall
 ```
 
 ## Solution Traits

src/initialization.jl

@@ -282,7 +282,17 @@ function get_initial_values(prob, valp, f, alg::OverrideInit,
             throw(OverrideInitNoTolerance(:reltol))
         end
         nlsol = solve(initprob, nlsolve_alg; abstol = _abstol, reltol = _reltol, kwargs...)
-        success = SciMLBase.successful_retcode(nlsol)
+
+        success = if initprob isa NonlinearLeastSquaresProblem
+            # Do not accept StalledSuccess as a solution
+            # A good local minima is not a success 
+            resid = nlsol.resid
+            normresid = isdefined(integrator.opts, :internalnorm) ?
+            integrator.opts.internalnorm(resid, t) : norm(resid)
+            SciMLBase.successful_retcode(nlsol) && normresid <= abstol
+        else
+            SciMLBase.successful_retcode(nlsol)
+        end
     end
 
     if initdata.initializeprobmap !== nothing

src/retcodes.jl

@@ -392,15 +392,36 @@ EnumX.@enumx ReturnCode begin
         ReturnCode.Stalled
 
     The solution has stalled. This is only returned by algorithms for which stalling is a
-    failure mode. Certain solvers like Nonlinear Least Squares solvers are considered
-    successful if the solution has stalled, in those cases `ReturnCode.Success` is returned.
+    failure mode, such as on a NonlinearProblem where the found solution is larger than
+    the accepted tolerance.
 
     ## Properties
 
       - `successful_retcode` = `false`
     """
     Stalled
 
+    """
+      ReturnCode.StalledSuccess
+
+    The solution process has stalled, but the stall is not considered a failure of the solver.
+    For example, a nonlinear optimizer may have stalled, that is its steps went to zero, which
+    is a valid local minima. 
+
+    ## Common Reasons for Seeing this Return Code
+
+      - For nonlinear least squares optimizations, this is given for local minima which exceed 
+        the chosen tolerance, i.e. `f(x)=resid` where `||resid||>tol` so it's not considered 
+        ReturnCode.Success but it is still considered a sucessful return of the solver since
+        it's a valid local minima (and there no minima which achieves the tolerance).
+
+    ## Properties
+
+      - `successful_retcode` = `true`
+
+    """
+    StalledSuccess
+
     """
         ReturnCode.InternalLinearSolveFailed
 
@@ -510,6 +531,7 @@ function successful_retcode(retcode::ReturnCode.T)
     retcode == ReturnCode.Success || retcode == ReturnCode.Terminated ||
         retcode == ReturnCode.ExactSolutionLeft ||
         retcode == ReturnCode.ExactSolutionRight ||
-        retcode == ReturnCode.FloatingPointLimit
+        retcode == ReturnCode.FloatingPointLimit ||
+        retcode == ReturnCode.StalledSuccess
 end
 successful_retcode(sol::AbstractSciMLSolution) = successful_retcode(sol.retcode)