Document public API coverage

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

Author: ChrisRackauckas

docs/src/basics/autodiff.md

@@ -1,5 +1,9 @@
 # Automatic Differentiation Backends
 
+```@docs
+BVPJacobianAlgorithm
+```
+
 !!! note
 
     We support ForwardDiff.jl, FiniteDiff.jl, Enzyme.jl, Mooncake.jl and PolyesterForwardDiff.jl(PolyesterForwardDiff only for collocation methods) via DifferentiationInterface.jl. Please refer to

docs/src/basics/solve.md

@@ -1,5 +1,9 @@
 # [Common Solver Options (Solve Keyword Arguments)](@id solver_options)
 
+```@docs
+integral
+```
+
   - `abstol::Number`: The absolute tolerance. Defaults to `1e-6`.
   - `adaptive::Bool`: Whether the error control adaptivity is on, default as `true`.
   - `controller`: Error controller for collocation methods, default as `DefectControl()`, more controller options in [Error Control Adaptivity](@ref error_control).

docs/src/basics/verbosity.md

@@ -70,4 +70,5 @@ sol = solve(prob, MIRK4(optimize = OptimizationOptimJL.BFGS()), dt = 0.1, verbos
 
 ```@docs
 BVPVerbosity
+DEFAULT_VERBOSE
 ```

docs/src/devdocs/internal_interfaces.md

@@ -5,3 +5,71 @@
 ```@docs
 BoundaryValueDiffEqCore.AbstractBoundaryValueDiffEqAlgorithm
 ```
+
+## Core Internal Interfaces
+
+```@docs
+BoundaryValueDiffEqCore.AbstractBoundaryValueDiffEqCache
+BoundaryValueDiffEqCore.AbstractErrorControl
+BoundaryValueDiffEqCore.DiffCacheNeeded
+BoundaryValueDiffEqCore.EvalSol
+BoundaryValueDiffEqCore.NoDiffCacheNeeded
+BoundaryValueDiffEqCore.__FastShortcutNonlinearPolyalg
+BoundaryValueDiffEqCore.__Fix3
+BoundaryValueDiffEqCore.__add_singular_term!
+BoundaryValueDiffEqCore.__any_sparse_ad
+BoundaryValueDiffEqCore.__build_cost
+BoundaryValueDiffEqCore.__build_solution
+BoundaryValueDiffEqCore.__cache_trait
+BoundaryValueDiffEqCore.__concrete_kwargs
+BoundaryValueDiffEqCore.__concrete_solve_algorithm
+BoundaryValueDiffEqCore.__construct_internal_problem
+BoundaryValueDiffEqCore.__default_coloring_algorithm
+BoundaryValueDiffEqCore.__default_nonsparse_ad
+BoundaryValueDiffEqCore.__default_sparse_ad
+BoundaryValueDiffEqCore.__default_sparsity_detector
+BoundaryValueDiffEqCore.__extract_mesh
+BoundaryValueDiffEqCore.__extract_problem_details
+BoundaryValueDiffEqCore.__extract_u0
+BoundaryValueDiffEqCore.__flatten_initial_guess
+BoundaryValueDiffEqCore.__get_bcresid_prototype
+BoundaryValueDiffEqCore.__get_non_sparse_ad
+BoundaryValueDiffEqCore.__has_initial_guess
+BoundaryValueDiffEqCore.__initial_guess
+BoundaryValueDiffEqCore.__initial_guess_length
+BoundaryValueDiffEqCore.__initial_guess_on_mesh
+BoundaryValueDiffEqCore.__internal_nlsolve_problem
+BoundaryValueDiffEqCore.__internal_optimization_problem
+BoundaryValueDiffEqCore.__internal_solve
+BoundaryValueDiffEqCore.__materialize_jacobian_algorithm
+BoundaryValueDiffEqCore.__maybe_allocate_diffcache
+BoundaryValueDiffEqCore.__maybe_matmul!
+BoundaryValueDiffEqCore.__needs_diffcache
+BoundaryValueDiffEqCore.__resize!
+BoundaryValueDiffEqCore.__restructure_sol
+BoundaryValueDiffEqCore.__split_kwargs
+BoundaryValueDiffEqCore.__tunable_part
+BoundaryValueDiffEqCore.__use_both_error_control
+BoundaryValueDiffEqCore.__vec
+BoundaryValueDiffEqCore.__vec_bc
+BoundaryValueDiffEqCore.__vec_bc!
+BoundaryValueDiffEqCore.__vec_f
+BoundaryValueDiffEqCore.__vec_f!
+BoundaryValueDiffEqCore.__vec_so_bc
+BoundaryValueDiffEqCore.__vec_so_bc!
+BoundaryValueDiffEqCore._process_verbose_param
+BoundaryValueDiffEqCore._sparse_like
+BoundaryValueDiffEqCore._unwrap_val
+BoundaryValueDiffEqCore.concrete_jacobian_algorithm
+BoundaryValueDiffEqCore.diff!
+BoundaryValueDiffEqCore.eval_bc_residual
+BoundaryValueDiffEqCore.eval_bc_residual!
+BoundaryValueDiffEqCore.get_dense_ad
+BoundaryValueDiffEqCore.interval
+BoundaryValueDiffEqCore.nodual_value
+BoundaryValueDiffEqCore.recursive_flatten
+BoundaryValueDiffEqCore.recursive_flatten!
+BoundaryValueDiffEqCore.recursive_flatten_twopoint!
+BoundaryValueDiffEqCore.recursive_unflatten!
+BoundaryValueDiffEqCore.safe_similar
+```

docs/src/solvers/mirk.md

@@ -28,4 +28,7 @@ MIRK3
 MIRK4
 MIRK5
 MIRK6
+MIRK6I
+maxsol
+minsol
 ```

lib/BoundaryValueDiffEqCore/src/calc_errors.jl

@@ -115,5 +115,10 @@ struct REErrorControl <: GlobalErrorControlMethod end
 
 # Some utils for error control adaptivity
 # If error control use both defect and global error or not
+"""
+    __use_both_error_control(controller) -> Bool
+
+Return whether an error controller combines defect and global error control.
+"""
 @inline __use_both_error_control(::HybridErrorControl) = true
 @inline __use_both_error_control(_) = false

lib/BoundaryValueDiffEqCore/src/default_internal_solve.jl

@@ -44,6 +44,13 @@ function __FastShortcutBVPCompatibleNonlinearPolyalg(
     return NonlinearSolvePolyAlgorithm(algs)
 end
 
+"""
+    __FastShortcutNonlinearPolyalg(T = Float64; concrete_jac = nothing, linsolve = nothing,
+        autodiff = nothing)
+
+Build the default nonlinear solver polyalgorithm used when a BVP algorithm does not supply
+an explicit nonlinear solver.
+"""
 function __FastShortcutNonlinearPolyalg(
         ::Type{T} = Float64; concrete_jac = nothing,
         linsolve = nothing, autodiff = nothing
@@ -91,7 +98,12 @@ end
     end
 end
 
-# Some optimization algorithms (solvers from interfacing packages) don't support the __solve(prob) interface
+"""
+    __internal_solve(prob, alg; kwargs...)
+
+Dispatch to the appropriate solve entry point for internal nonlinear, nonlinear least
+squares, and optimization problems.
+"""
 @inline __internal_solve(
     prob::Union{SciMLBase.NonlinearProblem, SciMLBase.NonlinearLeastSquaresProblem},
     alg; kwargs...

lib/BoundaryValueDiffEqCore/src/internal_problems.jl

@@ -1,5 +1,12 @@
 @inline __default_cost(::Nothing) = (x, p) -> 0.0
 @inline __default_cost(f) = f
+
+"""
+    __build_cost(fun, cache, mesh, M; tune_parameters = false, p = nothing)
+
+Build the objective function used by optimization-based BVP solves from a user supplied
+cost functional.
+"""
 @inline __build_cost(::Nothing, cache, mesh, M; kwargs...) = (x, p) -> 0.0
 @inline function __build_cost(fun, cache, mesh, M; tune_parameters = false, p = nothing)
     if tune_parameters && SciMLStructures.isscimlstructure(p)
@@ -79,6 +86,12 @@ end
     return lb, ub
 end
 
+"""
+    integral(fun, domain)
+
+Evaluate a one-dimensional integral over `domain` using the default `Integrals.QuadGKJL`
+backend.
+"""
 function integral(fun, domain)
     prob = IntegralProblem(fun, domain)
     sol = SciMLBase.solve(prob, Integrals.QuadGKJL())

lib/BoundaryValueDiffEqCore/src/solution_utils.jl

@@ -1,4 +1,10 @@
 # Intermediate solution evaluation
+"""
+    EvalSol(u, t, cache)
+
+Internal interpolatable solution wrapper used while forming collocation residuals and
+optimization objectives.
+"""
 @concrete struct EvalSol{C}
     u
     t

lib/BoundaryValueDiffEqCore/src/types.jl

@@ -1,10 +1,28 @@
 # Sparsity Detection
+"""
+    BVPJacobianAlgorithm(diffmode = missing; nonbc_diffmode = missing, bc_diffmode = missing)
+
+Select the automatic differentiation backends used to form boundary value problem
+Jacobians.
+
+For two-point problems, `diffmode` is used for the whole residual. For standard
+multi-point problems, `nonbc_diffmode` is used for the differential equation residual and
+`bc_diffmode` is used for the boundary condition residual. Passing `diffmode` fills both
+specialized fields unless they are supplied explicitly.
+"""
 @concrete struct BVPJacobianAlgorithm
     bc_diffmode
     nonbc_diffmode
     diffmode
 end
 
+"""
+    __materialize_jacobian_algorithm(nlsolve, jac_alg)
+
+Normalize a user supplied AD backend or Jacobian algorithm into a `BVPJacobianAlgorithm`.
+When `jac_alg` is not supplied, the nonlinear solver's `jacobian_ad` field is used if it
+exists.
+"""
 @inline __materialize_jacobian_algorithm(_, alg::BVPJacobianAlgorithm) = alg
 @inline __materialize_jacobian_algorithm(_, alg::ADTypes.AbstractADType) = BVPJacobianAlgorithm(alg)
 @inline __materialize_jacobian_algorithm(::Nothing, ::Nothing) = BVPJacobianAlgorithm()
@@ -30,6 +48,11 @@ function Base.show(io::IO, alg::BVPJacobianAlgorithm)
     return print(io, ")")
 end
 
+"""
+    __any_sparse_ad(ad_or_jac_alg) -> Bool
+
+Return whether an AD backend or `BVPJacobianAlgorithm` contains an `AutoSparse` backend.
+"""
 @inline __any_sparse_ad(::AutoSparse) = true
 @inline function __any_sparse_ad(jac_alg::BVPJacobianAlgorithm)
     return __any_sparse_ad(jac_alg.bc_diffmode) ||
@@ -104,6 +127,11 @@ function concrete_jacobian_algorithm(jac_alg::BVPJacobianAlgorithm, prob_type, p
     return BVPJacobianAlgorithm(bc_diffmode, nonbc_diffmode, diffmode)
 end
 
+"""
+    __default_sparse_ad(x_or_type)
+
+Choose the default sparse AD backend for an input value or element type.
+"""
 @inline function __default_sparse_ad(x::AbstractArray{T}) where {T}
     return isbitstype(T) ? __default_sparse_ad(T) : __default_sparse_ad(first(x))
 end
@@ -136,15 +164,33 @@ end
     )
 end
 
+"""
+    __default_coloring_algorithm(diffmode)
+
+Return the sparse matrix coloring algorithm associated with `diffmode`, or the package
+default when none is specified.
+"""
 @inline __default_coloring_algorithm(_) = GreedyColoringAlgorithm()
 @inline __default_coloring_algorithm(diffmode::AutoSparse) = isnothing(diffmode) ?
     GreedyColoringAlgorithm() :
     diffmode.coloring_algorithm
+
+"""
+    __default_sparsity_detector(diffmode)
+
+Return the sparsity detector associated with `diffmode`, or the package default when none
+is specified.
+"""
 @inline __default_sparsity_detector(_) = TracerLocalSparsityDetector()
 @inline __default_sparsity_detector(diffmode::AutoSparse) = isnothing(diffmode) ?
     TracerLocalSparsityDetector() :
     diffmode.sparsity_detector
 
+"""
+    __default_nonsparse_ad(x_or_type)
+
+Choose the default dense AD backend for an input value or element type.
+"""
 @inline function __default_nonsparse_ad(x::AbstractArray{T}) where {T}
     return isbitstype(T) ? __default_nonsparse_ad(T) : __default_nonsparse_ad(first(x))
 end
@@ -160,6 +206,12 @@ function concretize_jacobian_algorithm(alg, prob)
     return alg
 end
 
+"""
+    __needs_diffcache(ad_or_jac_alg) -> Bool
+
+Return whether the AD backend needs a `PreallocationTools.DiffCache` during residual or
+Jacobian evaluation.
+"""
 @inline __needs_diffcache(::AutoForwardDiff) = true
 @inline __needs_diffcache(::AutoPolyesterForwardDiff) = true
 @inline __needs_diffcache(ad::AutoSparse) = __needs_diffcache(ADTypes.dense_ad(ad))
@@ -170,6 +222,11 @@ end
         __needs_diffcache(jac_alg.nonbc_diffmode)
 end
 
+"""
+    __maybe_allocate_diffcache(x, chunksize, jac_alg)
+
+Allocate a `DiffCache` for `x` when `jac_alg` requires one; otherwise return `x`.
+"""
 function __maybe_allocate_diffcache(x, chunksize, jac_alg)
     return __needs_diffcache(jac_alg) ?
         DiffCache(x, chunksize; warn_on_resize = false) : x
@@ -179,9 +236,26 @@ function __maybe_allocate_diffcache(x::DiffCache, chunksize)
 end
 
 # DiffCache
+"""
+    DiffCacheNeeded
+
+Trait value indicating that a Jacobian backend needs a `DiffCache`.
+"""
 struct DiffCacheNeeded end
+
+"""
+    NoDiffCacheNeeded
+
+Trait value indicating that a Jacobian backend does not need a `DiffCache`.
+"""
 struct NoDiffCacheNeeded end
 
+"""
+    __cache_trait(ad_or_jac_alg)
+
+Return `DiffCacheNeeded()` or `NoDiffCacheNeeded()` for an AD backend or
+`BVPJacobianAlgorithm`.
+"""
 @inline __cache_trait(::AutoForwardDiff) = DiffCacheNeeded()
 @inline __cache_trait(ad::AutoSparse) = __cache_trait(ADTypes.dense_ad(ad))
 @inline function __cache_trait(jac_alg::BVPJacobianAlgorithm)