Merge pull request SciML#587 from SciML/ap/retcode

Standardizing NonlinearSolve Return Codes

Project.toml

@@ -1,109 +1,109 @@
-name = "SciMLBase"
-uuid = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
-authors = ["Chris Rackauckas <[email protected]> and contributors"]
-version = "2.18.0"
-
-[deps]
-ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
-ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
-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"
-FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
-FunctionWrappersWrappers = "77dc65aa-8811-40c2-897b-53d922fa7daf"
-IteratorInterfaceExtensions = "82899510-4779-5014-852e-03e436cf321d"
-LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
-Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
-PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
-Preferences = "21216c6a-2e73-6563-6e65-726566657250"
-Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
-RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
-RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
-Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
-RuntimeGeneratedFunctions = "7e49a35a-f44a-4d26-94aa-eba1b4ca6b47"
-SciMLOperators = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"
-StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
-Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
-SymbolicIndexingInterface = "2efcf032-c050-4f8e-a9bb-153293bab1f5"
-Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
-TruncatedStacktraces = "781d530d-4396-4725-bb49-402e4bee1e77"
-
-[weakdeps]
-ChainRules = "082447d4-558c-5d27-93f4-14fc19e9eca2"
-ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
-PartialFunctions = "570af359-4316-4cb7-8c74-252c00c2016b"
-PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
-PythonCall = "6099a3de-0909-46bc-b1f4-468b9a2dfc0d"
-RCall = "6f49c342-dc21-5d91-9882-a32aef131414"
-Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
-
-[extensions]
-SciMLBaseChainRulesCoreExt = "ChainRulesCore"
-SciMLBasePartialFunctionsExt = "PartialFunctions"
-SciMLBasePyCallExt = "PyCall"
-SciMLBasePythonCallExt = "PythonCall"
-SciMLBaseRCallExt = "RCall"
-SciMLBaseZygoteExt = "Zygote"
-
-[compat]
-ADTypes = "0.2.5"
-ArrayInterface = "7.6"
-ChainRules = "1.58.0"
-ChainRulesCore = "1.18"
-CommonSolve = "0.2.4"
-ConstructionBase = "1.5"
-DataFrames = "1.6"
-Distributed = "1.9"
-DocStringExtensions = "0.9"
-EnumX = "1"
-FillArrays = "1.9"
-FunctionWrappersWrappers = "0.1.3"
-IteratorInterfaceExtensions = "^1"
-LinearAlgebra = "1.9"
-Logging = "1.9"
-Markdown = "1.9"
-ModelingToolkit = "8.74"
-PartialFunctions = "1.1"
-PrecompileTools = "1.2"
-Preferences = "1.3"
-Printf = "1.9"
-PyCall = "1.96"
-PythonCall = "0.9.15"
-RCall = "0.14.0"
-RecipesBase = "1.0"
-RecursiveArrayTools = "3.3.4"
-Reexport = "1"
-RuntimeGeneratedFunctions = "0.5"
-SciMLOperators = "0.3.7"
-StaticArrays = "1.7"
-StaticArraysCore = "1.4"
-Statistics = "1.9"
-SymbolicIndexingInterface = "0.3.2"
-Tables = "1.11"
-TruncatedStacktraces = "1.4"
-Zygote = "0.6.67"
-julia = "1.9"
-
-[extras]
-Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
-ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
-DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
-DelayDiffEq = "bcd4f6db-9728-5f36-b5f7-82caef46ccdb"
-ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
-OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
-PartialFunctions = "570af359-4316-4cb7-8c74-252c00c2016b"
-Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
-PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
-PythonCall = "6099a3de-0909-46bc-b1f4-468b9a2dfc0d"
-RCall = "6f49c342-dc21-5d91-9882-a32aef131414"
-SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
-StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
-StochasticDiffEq = "789caeaf-c7a9-5a7d-9973-96adeb23e2a0"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
-
-[targets]
-test = ["Pkg", "PyCall", "PythonCall", "SafeTestsets", "Test", "StaticArrays", "StochasticDiffEq", "Aqua", "Zygote", "PartialFunctions", "DataFrames", "ModelingToolkit", "OrdinaryDiffEq"]
+name = "SciMLBase"
+uuid = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
+authors = ["Chris Rackauckas <[email protected]> and contributors"]
+version = "2.19.0"
+
+[deps]
+ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
+ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
+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"
+FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
+FunctionWrappersWrappers = "77dc65aa-8811-40c2-897b-53d922fa7daf"
+IteratorInterfaceExtensions = "82899510-4779-5014-852e-03e436cf321d"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+Preferences = "21216c6a-2e73-6563-6e65-726566657250"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
+RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
+RuntimeGeneratedFunctions = "7e49a35a-f44a-4d26-94aa-eba1b4ca6b47"
+SciMLOperators = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"
+StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+SymbolicIndexingInterface = "2efcf032-c050-4f8e-a9bb-153293bab1f5"
+Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
+TruncatedStacktraces = "781d530d-4396-4725-bb49-402e4bee1e77"
+
+[weakdeps]
+ChainRules = "082447d4-558c-5d27-93f4-14fc19e9eca2"
+ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
+PartialFunctions = "570af359-4316-4cb7-8c74-252c00c2016b"
+PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
+PythonCall = "6099a3de-0909-46bc-b1f4-468b9a2dfc0d"
+RCall = "6f49c342-dc21-5d91-9882-a32aef131414"
+Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
+
+[extensions]
+SciMLBaseChainRulesCoreExt = "ChainRulesCore"
+SciMLBasePartialFunctionsExt = "PartialFunctions"
+SciMLBasePyCallExt = "PyCall"
+SciMLBasePythonCallExt = "PythonCall"
+SciMLBaseRCallExt = "RCall"
+SciMLBaseZygoteExt = "Zygote"
+
+[compat]
+ADTypes = "0.2.5"
+ArrayInterface = "7.6"
+ChainRules = "1.58.0"
+ChainRulesCore = "1.18"
+CommonSolve = "0.2.4"
+ConstructionBase = "1.5"
+DataFrames = "1.6"
+Distributed = "1.9"
+DocStringExtensions = "0.9"
+EnumX = "1"
+FillArrays = "1.9"
+FunctionWrappersWrappers = "0.1.3"
+IteratorInterfaceExtensions = "^1"
+LinearAlgebra = "1.9"
+Logging = "1.9"
+Markdown = "1.9"
+ModelingToolkit = "8.74"
+PartialFunctions = "1.1"
+PrecompileTools = "1.2"
+Preferences = "1.3"
+Printf = "1.9"
+PyCall = "1.96"
+PythonCall = "0.9.15"
+RCall = "0.14.0"
+RecipesBase = "1.0"
+RecursiveArrayTools = "3.3.4"
+Reexport = "1"
+RuntimeGeneratedFunctions = "0.5"
+SciMLOperators = "0.3.7"
+StaticArrays = "1.7"
+StaticArraysCore = "1.4"
+Statistics = "1.9"
+SymbolicIndexingInterface = "0.3.2"
+Tables = "1.11"
+TruncatedStacktraces = "1.4"
+Zygote = "0.6.67"
+julia = "1.9"
+
+[extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+DelayDiffEq = "bcd4f6db-9728-5f36-b5f7-82caef46ccdb"
+ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+PartialFunctions = "570af359-4316-4cb7-8c74-252c00c2016b"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
+PythonCall = "6099a3de-0909-46bc-b1f4-468b9a2dfc0d"
+RCall = "6f49c342-dc21-5d91-9882-a32aef131414"
+SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+StochasticDiffEq = "789caeaf-c7a9-5a7d-9973-96adeb23e2a0"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
+
+[targets]
+test = ["Pkg", "PyCall", "PythonCall", "SafeTestsets", "Test", "StaticArrays", "StochasticDiffEq", "Aqua", "Zygote", "PartialFunctions", "DataFrames", "ModelingToolkit", "OrdinaryDiffEq"]

src/retcodes.jl

@@ -237,6 +237,9 @@ EnumX.@enumx ReturnCode begin
       nonlinear solver was chosen. If fixed point iteration is used on a stiff problem,
       it will be faster by avoiding the Jacobian but it will make a stiff ODE solver not
       stable for stiff problems!
+    * For nonlinear solvers, this can occur if certain threshold was exceeded. For example,
+      in approximate jacobian solvers like Broyden, Klement, etc. if the number of jacobian
+      resets exceeds the threshold, then this return code is given.
 
     ## Properties
 
@@ -343,6 +346,41 @@ EnumX.@enumx ReturnCode begin
     * successful_retcode = false
     """
     MaxTime
+
+    """
+    `ReturnCode.InternalLineSearchFailed`
+
+    Internal Line Search used by the algorithm has failed.
+
+    ## Properties
+
+    * successful_retcode = false
+    """
+    InternalLineSearchFailed
+
+    """
+    `ReturnCode.ShrinkThresholdExceeded`
+
+    The trust region radius was shrunk more times than the provided threshold.
+
+    ## Properties
+
+    * successful_retcode = false
+    """
+    ShrinkThresholdExceeded
+
+    """
+    `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.
+
+    ## Properties
+
+    * successful_retcode = false
+    """
+    Stalled
 end
 
 Base.:(!=)(retcode::ReturnCode.T, s::Symbol) = Symbol(retcode) != s