Document BoundaryValueDiffEqCore developer contracts

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>

Author: ChrisRackauckas

lib/BoundaryValueDiffEqCore/src/abstract_types.jl

@@ -4,15 +4,19 @@
 Developer-facing abstract type for BoundaryValueDiffEq solver caches.
 
 A solver package's `SciMLBase.__init` implementation returns a concrete subtype of this type.
-The cache must expose a `prob` field so the default `SciMLBase.isinplace(cache)` method can
-delegate to the boundary value problem, and the solver package must implement
-`SciMLBase.solve!(cache)`. This is a versioned interface for solver implementations, not an
-end-user extension point.
+This is a versioned developer interface for solver implementations, not an end-user extension
+point.
 
 # Interface
 
-- `SciMLBase.isinplace(cache)`: determines whether the cache's problem is in-place.
-- `Base.eltype(cache)`: returns the cache element type when the solver needs one.
+- Every cache must store the exact problem supplied to `SciMLBase.__init` in a field named
+  `prob`. The default `SciMLBase.isinplace(cache)` delegates to that field.
+- Every cache must implement `SciMLBase.solve!(cache)` and return the solver result expected by
+  its algorithm.
+- Define `Base.eltype(cache)` when the solver's implementation requires an element type.
+
+The cache and its `solve!` method must be owned by the package that owns the corresponding
+algorithm subtype. Do not extend another solver package's cache type.
 
 # Examples
 
@@ -23,7 +27,7 @@ struct MyBVPCache{P} <: AbstractBoundaryValueDiffEqCache
     prob::P
 end
 
-SciMLBase.solve!(cache::MyBVPCache) = nothing
+SciMLBase.solve!(cache::MyBVPCache) = cache.prob
 ```
 """
 abstract type AbstractBoundaryValueDiffEqCache end

lib/BoundaryValueDiffEqCore/src/algorithms.jl

@@ -5,21 +5,39 @@
 Developer-facing abstract type for boundary value problem algorithms.
 
 Packages that implement a BoundaryValueDiffEq solver subtype this type and implement the
-SciML solve interface for that algorithm. In particular, provide an
-`SciMLBase.__init(prob, alg; kwargs...)` method that constructs a solver cache and a
-corresponding `SciMLBase.solve!` method for that cache. Solver users should select a concrete
-algorithm such as `MIRK4()` or `Shooting()` rather than subtype this interface.
+SciML solve interface for that algorithm. This is a versioned developer interface for solver
+packages, not an end-user extension point. Solver users should select a concrete algorithm such
+as `MIRK4()` or `Shooting()` rather than subtype this interface.
+
+# Interface
+
+For every concrete subtype `Alg`, define:
+
+```julia
+SciMLBase.__init(prob::SciMLBase.AbstractBVProblem, alg::Alg, args...; kwargs...)
+```
+
+The method must return a concrete [`AbstractBoundaryValueDiffEqCache`](@ref) whose `prob` field
+is the supplied problem. It must accept and interpret the positional and keyword arguments that
+the solver package supports. The matching cache type must implement `SciMLBase.solve!(cache)`.
+`SciMLBase.solve(prob, alg, args...; kwargs...)` dispatches through these two methods in order;
+`solve!` returns the solver result. Do not add methods for algorithms owned by another package.
 
 # Examples
 
 ```julia
 using BoundaryValueDiffEqCore, SciMLBase
 
 struct MyBVPAlgorithm <: AbstractBoundaryValueDiffEqAlgorithm end
-
-function SciMLBase.__init(prob, ::MyBVPAlgorithm; kwargs...)
-    # Construct and return the cache consumed by SciMLBase.solve!.
+struct MyBVPCache{P} <: AbstractBoundaryValueDiffEqCache
+    prob::P
 end
+
+SciMLBase.__init(prob::SciMLBase.AbstractBVProblem, ::MyBVPAlgorithm; kwargs...) =
+    MyBVPCache(prob)
+SciMLBase.solve!(cache::MyBVPCache) = cache.prob
+
+SciMLBase.solve(prob, MyBVPAlgorithm()) # calls __init, then solve!
 ```
 
 See the concrete solver packages in this repository for complete implementations.

lib/BoundaryValueDiffEqCore/src/calc_errors.jl

@@ -1,7 +1,32 @@
 """
     AbstractErrorControl
 
-Abstract type for different error control methods.
+Developer-facing abstract type for error-controller tags used by BoundaryValueDiffEq solver
+implementations.
+
+This is a narrow versioned interface for solver packages. Subtypes classify how a solver's own
+adaptivity implementation manages error estimates; subtyping this type alone does not make a
+controller usable by `MIRK`, `FIRK`, or another concrete solver.
+
+# Extension Rules
+
+A solver package that owns both an error controller and the corresponding adaptivity behavior may
+subtype `AbstractErrorControl`. It may extend [`__use_both_error_control`](@ref) for that subtype
+to declare whether its cache requires separate defect and global-error storage. The method must
+return a `Bool`, be side-effect free, and be defined only for the extending package's controller
+type. The default is `false`.
+
+The concrete solver package remains responsible for implementing all controller-specific error
+estimation and mesh-selection behavior. Applications should use the documented concrete
+controllers rather than subtype this type.
+
+# Examples
+
+```julia
+struct MyCombinedControl <: AbstractErrorControl end
+
+BoundaryValueDiffEqCore.__use_both_error_control(::MyCombinedControl) = true
+```
 """
 abstract type AbstractErrorControl end
 
@@ -118,7 +143,21 @@ struct REErrorControl <: GlobalErrorControlMethod end
 """
     __use_both_error_control(controller) -> Bool
 
-Return whether an error controller combines defect and global error control.
+Return whether an error controller requires separate defect and global-error storage.
+
+This developer hook is used while a solver cache is constructed. The default implementation
+returns `false`. Solver packages may extend it only for their own
+[`AbstractErrorControl`](@ref) subtype, return a concrete `Bool`, and perform no mutation. A
+`true` result reserves storage for both estimates; it does not by itself add support for a custom
+controller to a concrete solver.
+
+# Examples
+
+```julia
+struct MyCombinedControl <: AbstractErrorControl end
+
+BoundaryValueDiffEqCore.__use_both_error_control(::MyCombinedControl) = true
+```
 """
 @inline __use_both_error_control(::HybridErrorControl) = true
 @inline __use_both_error_control(_) = false

lib/BoundaryValueDiffEqCore/test/Core/util_tests.jl

@@ -1,20 +1,57 @@
 using BoundaryValueDiffEqCore
+using SciMLBase
 using Test
 
 module ExternalBVPAlgorithmExtension
-    using BoundaryValueDiffEqCore
+    using BoundaryValueDiffEqCore, SciMLBase
 
     struct ExternalBVPAlgorithm <: BoundaryValueDiffEqCore.AbstractBoundaryValueDiffEqAlgorithm end
     struct ExternalBVPCache{P} <: BoundaryValueDiffEqCore.AbstractBoundaryValueDiffEqCache
         prob::P
+        init_arg::Symbol
+        adaptive::Bool
     end
+
+    SciMLBase.__init(
+        prob::SciMLBase.AbstractBVProblem, ::ExternalBVPAlgorithm, init_arg::Symbol;
+        adaptive = true, kwargs...
+    ) = ExternalBVPCache(prob, init_arg, adaptive)
+
+    SciMLBase.solve!(cache::ExternalBVPCache) =
+        (; prob = cache.prob, init_arg = cache.init_arg, adaptive = cache.adaptive)
+
+    struct ExternalCombinedErrorControl <: BoundaryValueDiffEqCore.AbstractErrorControl end
+
+    BoundaryValueDiffEqCore.__use_both_error_control(::ExternalCombinedErrorControl) = true
 end
 
 @testset "AbstractBoundaryValueDiffEqAlgorithm extension interface" begin
     @test ExternalBVPAlgorithmExtension.ExternalBVPAlgorithm <:
     BoundaryValueDiffEqCore.AbstractBoundaryValueDiffEqAlgorithm
     @test ExternalBVPAlgorithmExtension.ExternalBVPCache <:
     BoundaryValueDiffEqCore.AbstractBoundaryValueDiffEqCache
+
+    f(u, p, t) = u
+    bc(u, p, t) = u
+    prob = SciMLBase.BVProblem(f, bc, [1.0], (0.0, 1.0))
+    sol = SciMLBase.solve(
+        prob, ExternalBVPAlgorithmExtension.ExternalBVPAlgorithm(), :from_solve;
+        adaptive = false
+    )
+
+    @test sol.prob === prob
+    @test sol.init_arg === :from_solve
+    @test !sol.adaptive
+    @test !SciMLBase.isinplace(
+        ExternalBVPAlgorithmExtension.ExternalBVPCache(prob, :test, true)
+    )
+end
+
+@testset "AbstractErrorControl extension interface" begin
+    @test !BoundaryValueDiffEqCore.__use_both_error_control(DefectControl())
+    @test BoundaryValueDiffEqCore.__use_both_error_control(
+        ExternalBVPAlgorithmExtension.ExternalCombinedErrorControl()
+    )
 end
 
 @testset "__extract_lcons_ucons length" begin