Make DiffEqBase.NAN_CHECK public API (#4093)

NAN_CHECK is the hook the integrators use to detect a step that produced NaN,
and downstream state types need a method on it for that detection to reach
their elements, so it is already used as public API without being declared
one. Declare it public alongside the other default-callback hooks, document
it, and render it on the DiffEqBase API page.

Co-authored-by: Chris Rackauckas <accounts@chrisrackauckas.com>

Author: ChrisRackauckas-Claude

docs/src/api/diffeqbase.md

@@ -27,6 +27,7 @@ DiffEqBase.ODE_DEFAULT_ISOUTOFDOMAIN
 DiffEqBase.ODE_DEFAULT_NORM
 DiffEqBase.ODE_DEFAULT_PROG_MESSAGE
 DiffEqBase.ODE_DEFAULT_UNSTABLE_CHECK
+DiffEqBase.NAN_CHECK
 ```
 
 ## Runge-Kutta tableau types

lib/DiffEqBase/Project.toml

@@ -1,7 +1,7 @@
 name = "DiffEqBase"
 uuid = "2b5f629d-d688-5b77-993f-72d75c75574e"
 authors = ["Chris Rackauckas <accounts@chrisrackauckas.com>"]
-version = "7.10.0"
+version = "7.11.0"
 
 [deps]
 ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"

lib/DiffEqBase/src/DiffEqBase.jl

@@ -211,7 +211,7 @@ export AutoDePSpecialize
             :max_vector_callback_length, :max_vector_callback_length_int, :get_condition,
             # Default-callback API (integrator defaults overridable via solver keywords)
             :ODE_DEFAULT_NORM, :ODE_DEFAULT_ISOUTOFDOMAIN, :ODE_DEFAULT_PROG_MESSAGE,
-            :ODE_DEFAULT_UNSTABLE_CHECK,
+            :ODE_DEFAULT_UNSTABLE_CHECK, :NAN_CHECK,
             # Tableau extension supertypes downstream tableau packages subtype
             :Tableau, :ODERKTableau,
             # Error-estimate residual hooks solvers call/extend

lib/DiffEqBase/src/common_defaults.jl

@@ -159,6 +159,25 @@ function ODE_DEFAULT_PROG_MESSAGE(dt, u, p, t)
     return "dt=" * string(dt) * "\nt=" * string(t) * "\nmax u=" * string(maximum(abs.(u)))
 end
 
+"""
+    NAN_CHECK(x)
+
+Recursively test whether `x` holds a `NaN`. The integrators use this to detect a step
+that produced `NaN` and reject it.
+
+Methods are provided for numbers, `AbstractArray`s, `RecursiveArrayTools.AbstractVectorOfArray`s
+and `RecursiveArrayTools.ArrayPartition`s; nested containers are descended into, so a state
+made of arrays of arrays reports `true` if any leaf is `NaN`. `Enum` values always report
+`false`, which keeps discrete components of a mixed state vector from being sent through
+`isnan`. Add a method to make the check reach the elements of a custom state type:
+
+```julia
+DiffEqBase.NAN_CHECK(x::MyStateType) = any(DiffEqBase.NAN_CHECK, x.parts)
+```
+
+`NaN` is only one of the ways a step can go bad; `Inf` and overflow are handled separately
+by [`ODE_DEFAULT_UNSTABLE_CHECK`](@ref).
+"""
 NAN_CHECK(x::Number) = isnan(x)
 NAN_CHECK(x::Enum) = false
 function NAN_CHECK(x::Union{AbstractArray, RecursiveArrayTools.AbstractVectorOfArray})

lib/DiffEqBase/test/ode_default_unstable_check.jl

@@ -1,6 +1,10 @@
 using Test, RecursiveArrayTools, StaticArrays, SparseArrays
 
-using DiffEqBase: NAN_CHECK
+using DiffEqBase: DiffEqBase, NAN_CHECK
+
+@static if VERSION >= v"1.11"
+    @test Base.ispublic(DiffEqBase, :NAN_CHECK)
+end
 
 @test !NAN_CHECK(3.0 + 4.0im)
 @test NAN_CHECK(NaN)