From 9c22374920dbd3622f66aa6a45ee42346a18385e Mon Sep 17 00:00:00 2001 From: ChrisRackauckas Date: Wed, 23 Jul 2025 07:16:49 -0400 Subject: [PATCH 1/3] Update return code documentation to reflect enum implementation (fixes #734) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update retcode documentation to explain they are now enum values, not symbols - Add proper usage example with SciMLBase.successful_retcode(sol) - Add warning about deprecated sol.retcode == :Success pattern - Fix incorrect usage in FAQ (was sol.retcode, should be just sol) - Add link to SciMLBase ReturnCode documentation for complete reference This addresses the issue where the documentation was outdated and still described return codes as symbols instead of the current enum implementation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/src/basics/faq.md | 2 +- docs/src/basics/solution.md | 37 ++++++++++++++++++++++++++----------- 2 files changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/src/basics/faq.md b/docs/src/basics/faq.md index 243c03282..a823f4e10 100644 --- a/docs/src/basics/faq.md +++ b/docs/src/basics/faq.md @@ -32,7 +32,7 @@ the solution quickly diverges to infinity! This means, double-check your paramet are indexed correctly! **Note: if you see these warnings during a parameter estimation process, this is -likely the underlying problem. Simply check `SciMLBase.successful_retcode(sol.retcode)` and throw +likely the underlying problem. Simply check `SciMLBase.successful_retcode(sol)` and throw an `Inf` cost. Most optimizers will then reject steps in those parameter regimes!** There are a few other things to check as well. Often, the stability of diff --git a/docs/src/basics/solution.md b/docs/src/basics/solution.md index 6c8a5b487..1b5efebc0 100644 --- a/docs/src/basics/solution.md +++ b/docs/src/basics/solution.md @@ -181,23 +181,38 @@ SciMLBase.DEStats ## [Return Codes (RetCodes)](@id retcodes) -The solution types have a `retcode` field which returns a symbol signifying the -error state of the solution. The retcodes are as follows: +The solution types have a `retcode` field which returns an enum value signifying the +error state of the solution. Return codes are now implemented as an enum using EnumX.jl +rather than symbols. - - `:Default`: The solver did not set retcodes. - - `:Success`: The integration completed without erroring or the steady state solver +To check if a solution was successful, use: +```julia +SciMLBase.successful_retcode(sol) +``` + +!!! warning + Previous iterations of the interface suggested using `sol.retcode == :Success`, + however, that is now not advised. Use `SciMLBase.successful_retcode(sol)` instead. + +The return codes include: + + - `Default`: The solver did not set retcodes. + - `Success`: The integration completed without erroring or the steady state solver from `SteadyStateDiffEq` found the steady state. - - `:Terminated`: The integration is terminated with `terminate!(integrator)`. + - `Terminated`: The integration is terminated with `terminate!(integrator)`. Note that this may occur by using `TerminateSteadyState` from the callback library `DiffEqCallbacks`. - - `:MaxIters`: The integration exited early because it reached its maximum number + - `MaxIters`: The integration exited early because it reached its maximum number of iterations. - - `:DtLessThanMin`: The timestep method chose a stepsize which is smaller than the + - `DtLessThanMin`: The timestep method chose a stepsize which is smaller than the allowed minimum timestep, and exited early. - - `:Unstable`: The solver detected that the solution was unstable and exited early. - - `:InitialFailure`: The DAE solver could not find consistent initial conditions. - - `:ConvergenceFailure`: The internal implicit solvers failed to converge. - - `:Failure`: General uncategorized failures or errors. + - `Unstable`: The solver detected that the solution was unstable and exited early. + - `InitialFailure`: The DAE solver could not find consistent initial conditions. + - `ConvergenceFailure`: The internal implicit solvers failed to converge. + - `Failure`: General uncategorized failures or errors. + +For a complete list of return codes and their properties, see the +[SciMLBase ReturnCode documentation](https://docs.sciml.ai/SciMLBase/stable/interfaces/Solutions/#retcodes). ## Problem-Specific Features From c4dfcce6a4339fe69a650c66212340435303657c Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Wed, 23 Jul 2025 09:16:05 -0400 Subject: [PATCH 2/3] Update docs/src/basics/solution.md --- docs/src/basics/solution.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/basics/solution.md b/docs/src/basics/solution.md index 1b5efebc0..b73ffa512 100644 --- a/docs/src/basics/solution.md +++ b/docs/src/basics/solution.md @@ -192,7 +192,9 @@ SciMLBase.successful_retcode(sol) !!! warning Previous iterations of the interface suggested using `sol.retcode == :Success`, - however, that is now not advised. Use `SciMLBase.successful_retcode(sol)` instead. + however, that is now not advised because there are more than one return code that can be interpreted + as successful. For example, `Terminated` is a successful run to a manual termination, and would be missed + if only checking for Success. Therefore we highly recommend you use `SciMLBase.successful_retcode(sol)` instead. The return codes include: From 3865303422a2e98dd571327347ce74bf5dcbef35 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Wed, 23 Jul 2025 09:17:11 -0400 Subject: [PATCH 3/3] Update docs/src/basics/solution.md --- docs/src/basics/solution.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/src/basics/solution.md b/docs/src/basics/solution.md index b73ffa512..21795804a 100644 --- a/docs/src/basics/solution.md +++ b/docs/src/basics/solution.md @@ -196,7 +196,8 @@ SciMLBase.successful_retcode(sol) as successful. For example, `Terminated` is a successful run to a manual termination, and would be missed if only checking for Success. Therefore we highly recommend you use `SciMLBase.successful_retcode(sol)` instead. -The return codes include: +The return codes include are accessed via the ReturnCode module, i.e. `SciMLBase.ReturnCode.Success`. The +following are major return codes to know: - `Default`: The solver did not set retcodes. - `Success`: The integration completed without erroring or the steady state solver