Safely update retcodes to enums

Project.toml

@@ -9,6 +9,7 @@ CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
 ConstructionBase = "187b0558-2788-49d3-abe0-74a17ed4e7c9"
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+EnumX = "4e289a0a-7415-4d19-859d-a7e5c4648b56"
 FunctionWrappersWrappers = "77dc65aa-8811-40c2-897b-53d922fa7daf"
 IteratorInterfaceExtensions = "82899510-4779-5014-852e-03e436cf321d"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -27,6 +28,7 @@ ArrayInterfaceCore = "0.1.1"
 CommonSolve = "0.2"
 ConstructionBase = "1"
 DocStringExtensions = "0.8, 0.9"
+EnumX = "1"
 FunctionWrappersWrappers = "0.1"
 IteratorInterfaceExtensions = "^0.1, ^1"
 Preferences = "1.3"

src/SciMLBase.jl

@@ -14,6 +14,7 @@ import IteratorInterfaceExtensions
 import CommonSolve: solve, init, solve!
 import FunctionWrappersWrappers
 import RuntimeGeneratedFunctions
+import EnumX
 
 function __solve end
 function __init end
@@ -602,6 +603,7 @@ $(TYPEDEF)
 """
 abstract type AbstractParameterizedFunction{iip} <: AbstractODEFunction{iip} end
 
+include("retcodes.jl")
 include("operators/operators.jl")
 include("operators/basic_operators.jl")
 include("operators/diffeq_operator.jl")
@@ -667,6 +669,8 @@ const DEAlgorithm = AbstractDEAlgorithm
 const DESolution = AbstractSciMLSolution
 const SciMLSolution = AbstractSciMLSolution
 
+export ReturnCode
+
 export DEAlgorithm, SciMLAlgorithm, DEProblem, DEAlgorithm, DESolution, SciMLSolution
 
 # Exports

src/integrator_interface.jl

@@ -495,13 +495,13 @@ function check_error(integrator::DEIntegrator)
         if integrator.opts.verbose
             @warn("NaN dt detected. Likely a NaN value in the state, parameters, or derivative value caused this outcome.")
         end
-        return :DtNaN
+        return ReturnCode.DtNaN
     end
     if integrator.iter > integrator.opts.maxiters
         if integrator.opts.verbose
             @warn("Interrupted. Larger maxiters is needed. If you are using an integrator for non-stiff ODEs or an automatic switching algorithm (the default), you may want to consider using a method for stiff equations. See the solver pages for more details (e.g. https://diffeq.sciml.ai/stable/solvers/ode_solve/#Stiff-Problems).")
         end
-        return :MaxIters
+        return ReturnCode.MaxIters
     end
 
     # The last part:
@@ -515,22 +515,22 @@ function check_error(integrator::DEIntegrator)
         if integrator.opts.verbose
             @warn("dt($(integrator.dt)) <= dtmin($(integrator.opts.dtmin)) at t=$(integrator.t). Aborting. There is either an error in your model specification or the true solution is unstable.")
         end
-        return :DtLessThanMin
+        return ReturnCode.DtLessThanMin
     end
     if integrator.opts.unstable_check(integrator.dt, integrator.u, integrator.p,
                                       integrator.t)
         if integrator.opts.verbose
             @warn("Instability detected. Aborting")
         end
-        return :Unstable
+        return ReturnCode.Unstable
     end
     if last_step_failed(integrator)
         if integrator.opts.verbose
             @warn("Newton steps could not converge and algorithm is not adaptive. Use a lower dt.")
         end
-        return :ConvergenceFailure
+        return ReturnCode.ConvergenceFailure
     end
-    return :Success
+    return ReturnCode.Success
 end
 
 function postamble! end
@@ -543,7 +543,7 @@ Same as `check_error` but also set solution's return code
 """
 function check_error!(integrator::DEIntegrator)
     code = check_error(integrator)
-    if code != :Success
+    if code != ReturnCode.Success
         integrator.sol = solution_new_retcode(integrator.sol, code)
         postamble!(integrator)
     end
@@ -552,7 +552,7 @@ end
 
 ### Default Iterator Interface
 function done(integrator::DEIntegrator)
-    if !(integrator.sol.retcode in (:Default, :Success))
+    if !(integrator.sol.retcode in (ReturnCode.Default, ReturnCode.Success))
         return true
     elseif isempty(integrator.opts.tstops)
         postamble!(integrator)
@@ -781,7 +781,7 @@ function step!(integ::DEIntegrator, dt, stop_at_tdt = false)
     stop_at_tdt && add_tstop!(integ, next_t)
     while integ.t * integ.tdir < next_t * integ.tdir
         step!(integ)
-        integ.sol.retcode in (:Default, :Success) || break
+        integ.sol.retcode in (ReturnCode.Default, ReturnCode.Success) || break
     end
 end
 

src/retcodes.jl

@@ -0,0 +1,41 @@
+EnumX.@enumx(ReturnCode, Default, Success, Terminated, MaxIters, DtLessThanMin, Unstable,
+             InitialFailure, ConvergenceFailure, Failure)
+
+Base.convert(::Type{Symbol}, retcode::ReturnCode.T) = Symbol(retcode)
+
+Base.:(==)(retcode::ReturnCode.T, s::Symbol) = Symbol(retcode) == s
+Base.:(!=)(retcode::ReturnCode.T, s::Symbol) = Symbol(retcode) != s
+
+const symtrue = Symbol("true")
+const symfalse = Symbol("false")
+
+function Base.convert(::Type{ReturnCode.T}, retcode::Symbol)
+    if retcode == :Default || retcode == :DEFAULT
+        ReturnCode.Default
+    elseif retcode == :Success || retcode == :EXACT_SOLUTION_LEFT ||
+           retcode == :FLOATING_POINT_LIMIT || retcode == symtrue
+        ReturnCode.Success
+    elseif retcode == :Terminated
+        ReturnCode.Terminated
+    elseif retcode == :MaxIters || retcode == :MAXITERS_EXCEED
+        ReturnCode.MaxIters
+    elseif retcode == :DtLessThanMin
+        ReturnCode.DtLessThanMin
+    elseif retcode == :Unstable
+        ReturnCode.Unstable
+    elseif retcode == :InitialFailure
+        ReturnCode.InitialFailure
+    elseif retcode == :ConvergenceFailure || retcode == :ITERATION_LIMIT
+        ReturnCode.ConvergenceFailure
+    elseif retcode == :Failure || retcode == symfalse
+        ReturnCode.Failure
+    else
+        ReturnCode.Failure
+    end
+end
+
+function Base.convert(::Type{ReturnCode.T}, bool::Bool)
+    bool ? ReturnCode.Success : ReturnCode.Failure
+end
+
+successful_retcode(retcode::ReturnCode.T) = retcode == :Success || retcode == :Terminated

src/solutions/basic_solutions.jl

@@ -11,8 +11,8 @@ Representation of the solution to an linear system Ax=b defined by a LinearProbl
 - `iters`: the number of iterations used to solve the equation, if the method is an iterative
   method.
 - `retcode`: the return code from the solver. Used to determine whether the solver solved
-  successfully (`sol.retcode === :Success`), whether it terminated due to a user-defined
-  callback (`sol.retcode === :Terminated`), or whether it exited due to an error. For more
+  successfully (`sol.retcode === SciMLBase.Success`), whether it terminated due to a user-defined
+  callback (`sol.retcode === SciMLBase.Terminated`), or whether it exited due to an error. For more
   details, see the return code section of the DifferentialEquations.jl documentation.
 - `cache`: the `LinearCache` object containing the solver's internal cached variables. This
   is given to allow continuation of solver usage, for example, solving `Ax=b` with the same
@@ -23,13 +23,13 @@ struct LinearSolution{T, N, uType, R, A, C} <: AbstractLinearSolution{T, N}
     u::uType
     resid::R
     alg::A
-    retcode::Symbol
+    retcode::ReturnCode.T
     iters::Int
     cache::C
 end
 
 function build_linear_solution(alg, u, resid, cache;
-                               retcode = :Default,
+                               retcode = ReturnCode.Default,
                                iters = 0)
     T = eltype(eltype(u))
     N = length((size(u)...,))
@@ -49,8 +49,8 @@ Representation of the solution to an quadrature integral_lb^ub f(x) dx defined b
 - `resid`: the residual of the solver.
 - `alg`: the algorithm type used by the solver.
 - `retcode`: the return code from the solver. Used to determine whether the solver solved
-  successfully (`sol.retcode === :Success`), whether it terminated due to a user-defined
-  callback (`sol.retcode === :Terminated`), or whether it exited due to an error. For more
+  successfully (`sol.retcode === ReturnCode.Success`), whether it terminated due to a user-defined
+  callback (`sol.retcode === ReturnCode.Terminated`), or whether it exited due to an error. For more
   details, see the return code section of the DifferentialEquations.jl documentation.
 - `chi`: the variance estimate of the estimator from Monte Carlo quadrature methods.
 """
@@ -59,7 +59,7 @@ struct IntegralSolution{T, N, uType, R, P, A, C} <: AbstractIntegralSolution{T,
     resid::R
     prob::P
     alg::A
-    retcode::Symbol
+    retcode::ReturnCode.T
     chi::C
 end
 
@@ -69,7 +69,7 @@ struct QuadratureSolution end
 function build_solution(prob::AbstractIntegralProblem,
                         alg, u, resid; calculate_error = true,
                         chi = nothing,
-                        retcode = :Default, kwargs...)
+                        retcode = ReturnCode.Default, kwargs...)
     T = eltype(eltype(u))
     N = length((size(u)...,))
 

src/solutions/dae_solutions.jl

@@ -14,7 +14,7 @@ https://diffeq.sciml.ai/stable/basics/solution/
 
 - `u`: the representation of the DAE solution. Given as an array of solutions, where `u[i]`
   corresponds to the solution at time `t[i]`. It is recommended in most cases one does not
-  access `sol.u` directly and instead use the array interface described in the Solution 
+  access `sol.u` directly and instead use the array interface described in the Solution
   Handling page of the DifferentialEquations.jl documentation.
 - `du`: the representation of the derivatives of the DAE solution.
 - `t`: the time points corresponding to the saved values of the DAE solution.
@@ -23,8 +23,8 @@ https://diffeq.sciml.ai/stable/basics/solution/
 - `destats`: statistics of the solver, such as the number of function evaluations required,
   number of Jacobians computed, and more.
 - `retcode`: the return code from the solver. Used to determine whether the solver solved
-  successfully (`sol.retcode === :Success`), whether it terminated due to a user-defined
-  callback (`sol.retcode === :Terminated`), or whether it exited due to an error. For more
+  successfully (`sol.retcode === ReturnCode.Success`), whether it terminated due to a user-defined
+  callback (`sol.retcode === ReturnCode.Terminated`), or whether it exited due to an error. For more
   details, see the return code section of the DifferentialEquations.jl documentation.
 """
 struct DAESolution{T, N, uType, duType, uType2, DType, tType, P, A, ID, DE} <:
@@ -40,7 +40,7 @@ struct DAESolution{T, N, uType, duType, uType2, DType, tType, P, A, ID, DE} <:
     dense::Bool
     tslocation::Int
     destats::DE
-    retcode::Symbol
+    retcode::ReturnCode.T
 end
 function (sol::DAESolution)(t, ::Type{deriv} = Val{0}; idxs = nothing,
                             continuity = :left) where {deriv}
@@ -59,7 +59,7 @@ function build_solution(prob::AbstractDAEProblem, alg, t, u, du = nothing;
                         k = nothing,
                         interp = du === nothing ? LinearInterpolation(t, u) :
                                  HermiteInterpolation(t, u, du),
-                        retcode = :Default,
+                        retcode = ReturnCode.Default,
                         destats = nothing,
                         kwargs...)
     T = eltype(eltype(u))

src/solutions/nonlinear_solutions.jl

@@ -13,8 +13,8 @@ or the steady state solution to a differential equation defined by a SteadyState
 - `original`: if the solver is wrapped from an alternative solver ecosystem, such as
   NLsolve.jl, then this is the original return from said solver library.
 - `retcode`: the return code from the solver. Used to determine whether the solver solved
-  successfully (`sol.retcode === :Success`), whether it terminated due to a user-defined
-  callback (`sol.retcode === :Terminated`), or whether it exited due to an error. For more
+  successfully (`sol.retcode === ReturnCode.Success`), whether it terminated due to a user-defined
+  callback (`sol.retcode === ReturnCode.Terminated`), or whether it exited due to an error. For more
   details, see the return code section of the DifferentialEquations.jl documentation.
 - `left`: if the solver is bracketing method, this is the final left bracket value.
 - `right`: if the solver is bracketing method, this is the final right bracket value.
@@ -24,7 +24,7 @@ struct NonlinearSolution{T, N, uType, R, P, A, O, uType2} <: AbstractNonlinearSo
     resid::R
     prob::P
     alg::A
-    retcode::Symbol
+    retcode::ReturnCode.T
     original::O
     left::uType2
     right::uType2
@@ -34,7 +34,7 @@ const SteadyStateSolution = NonlinearSolution
 
 function build_solution(prob::AbstractNonlinearProblem,
                         alg, u, resid; calculate_error = true,
-                        retcode = :Default,
+                        retcode = ReturnCode.Default,
                         original = nothing,
                         left = nothing,
                         right = nothing,

src/solutions/ode_solutions.jl

@@ -22,7 +22,7 @@ https://diffeq.sciml.ai/stable/basics/solution/
 - `destats`: statistics of the solver, such as the number of function evaluations required,
   number of Jacobians computed, and more.
 - `retcode`: the return code from the solver. Used to determine whether the solver solved
-  successfully (`sol.retcode === :Success`), whether it terminated due to a user-defined
+  successfully (`sol.retcode === ReturnCode.Success`), whether it terminated due to a user-defined
   callback (`sol.retcode === :Terminated`), or whether it exited due to an error. For more
   details, see the return code section of the DifferentialEquations.jl documentation.
 """
@@ -39,7 +39,7 @@ struct ODESolution{T, N, uType, uType2, DType, tType, rateType, P, A, IType, DE}
     dense::Bool
     tslocation::Int
     destats::DE
-    retcode::Symbol
+    retcode::ReturnCode.T
 end
 function ODESolution{T, N}(u, u_analytic, errors, t, k, prob, alg, interp, dense,
                            tslocation, destats, retcode) where {T, N}
@@ -134,7 +134,7 @@ function build_solution(prob::Union{AbstractODEProblem, AbstractDDEProblem},
                         calculate_error = true,
                         k = nothing,
                         interp = LinearInterpolation(t, u),
-                        retcode = :Default, destats = nothing, kwargs...)
+                        retcode = ReturnCode.Default, destats = nothing, kwargs...)
     T = eltype(eltype(u))
 
     if prob.u0 === nothing

src/solutions/optimization_solutions.jl

@@ -13,7 +13,7 @@ Representation of the solution to an nonlinear optimization defined by an Optimi
 - `original`: if the solver is wrapped from an alternative solver ecosystem, such as
   Optim.jl, then this is the original return from said solver library.
 - `retcode`: the return code from the solver. Used to determine whether the solver solved
-  successfully (`sol.retcode === :Success`), whether it terminated due to a user-defined
+  successfully (`sol.retcode === ReturnCode.Success`), whether it terminated due to a user-defined
   callback (`sol.retcode === :Terminated`), or whether it exited due to an error. For more
   details, see the return code section of the DifferentialEquations.jl documentation.
 """
@@ -22,13 +22,13 @@ struct OptimizationSolution{T, N, uType, P, A, Tf, O} <: AbstractOptimizationSol
     prob::P # optimization problem
     alg::A # algorithm
     minimum::Tf
-    retcode::Symbol
+    retcode::ReturnCode.T
     original::O # original output of the optimizer
 end
 
 function build_solution(prob::AbstractOptimizationProblem,
                         alg, u, minimum;
-                        retcode = :Default,
+                        retcode = ReturnCode.Default,
                         original = nothing,
                         kwargs...)
     T = eltype(eltype(u))

src/solutions/pde_solutions.jl

@@ -25,8 +25,8 @@ Solution to a PDE, solved from an ODEProblem generated by a discretizer.
 - `alg`: The algorithm used to solve the ODEProblem.
 - `interp`: Interpolations for the solution.
 - `retcode`: The return code from the solver. Used to determine whether the solver solved
-  successfully (`sol.retcode === :Success`), whether it terminated due to a user-defined
-  callback (`sol.retcode === :Terminated`), or whether it exited due to an error. For more
+  successfully (`sol.retcode === ReturnCode.Success`), whether it terminated due to a user-defined
+  callback (`sol.retcode === ReturnCode.Terminated`), or whether it exited due to an error. For more
   details, see the return code section of the ODEProblem.jl documentation.
 """
 struct PDETimeSeriesSolution{T, N, uType, Disc, Sol, DType, tType, domType, ivType, dvType,
@@ -45,7 +45,7 @@ struct PDETimeSeriesSolution{T, N, uType, Disc, Sol, DType, tType, domType, ivTy
     interp::IType
     dense::Bool
     tslocation::Int
-    retcode::Symbol
+    retcode::ReturnCode.T
 end
 
 """
@@ -73,8 +73,8 @@ Solution to a PDE, solved from an NonlinearProblem generated by a discretizer.
 - `alg`: The algorithm used to solve the NonlinearProblem.
 - `interp`: Interpolations for the solution.
 - `retcode`: The return code from the solver. Used to determine whether the solver solved
-  successfully (`sol.retcode === :Success`), whether it terminated due to a user-defined
-  callback (`sol.retcode === :Terminated`), or whether it exited due to an error. For more
+  successfully (`sol.retcode === ReturnCode.Success`), whether it terminated due to a user-defined
+  callback (`sol.retcode === ReturnCode.Terminated`), or whether it exited due to an error. For more
   details, see the return code section of the ODEProblem.jl documentation.
 """
 struct PDENoTimeSolution{T, N, uType, Disc, Sol, domType, ivType, dvType, P, A,
@@ -88,7 +88,7 @@ struct PDENoTimeSolution{T, N, uType, Disc, Sol, domType, ivType, dvType, P, A,
     prob::P
     alg::A
     interp::IType
-    retcode::Symbol
+    retcode::ReturnCode.T
 end
 
 const PDESolution{T, N, S, D} = Union{PDETimeSeriesSolution{T, N, S, D},