Internal Abstract Types

AbstractBoundaryValueDiffEqAlgorithm

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. 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:

SciMLBase.__init(prob::SciMLBase.AbstractBVProblem, alg::Alg, args...; kwargs...)

The method must return a concrete AbstractBoundaryValueDiffEqCache 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

using BoundaryValueDiffEqCore, SciMLBase

struct MyBVPAlgorithm <: AbstractBoundaryValueDiffEqAlgorithm end
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.

AbstractBoundaryValueDiffEqCache

Developer-facing abstract type for BoundaryValueDiffEq solver caches.

A solver package's SciMLBase.__init implementation returns a concrete subtype of this type. This is a versioned developer interface for solver implementations, not an end-user extension point.

Interface

• 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

using BoundaryValueDiffEqCore, SciMLBase

struct MyBVPCache{P} <: AbstractBoundaryValueDiffEqCache
    prob::P
end

SciMLBase.solve!(cache::MyBVPCache) = cache.prob

AbstractErrorControl

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 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

struct MyCombinedControl <: AbstractErrorControl end

BoundaryValueDiffEqCore.__use_both_error_control(::MyCombinedControl) = true

DiffCacheNeeded

Trait value indicating that a Jacobian backend needs a DiffCache.

EvalSol(u, t, cache)

Internal interpolatable solution wrapper used while forming collocation residuals and optimization objectives.

NoDiffCacheNeeded

Trait value indicating that a Jacobian backend does not need a DiffCache.

__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.

__Fix3(f, x)

Callable helper that fixes the third argument of a three-argument function.

__add_singular_term!(K, singular_term, y, t)

Helper function to add the singular term contribution S * y / t to K for t > 0. Used in collocation residual computation for singular BVPs of the form y' = S*y/t + f(t,y).

__any_sparse_ad(ad_or_jac_alg) -> Bool

Return whether an AD backend or BVPJacobianAlgorithm contains an AutoSparse backend.

__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.

__build_solution(prob, odesol, nonlinear_or_optimization_solution)

Combine the interpolating ODE-style solution with the internal nonlinear or optimization solver result and propagate the appropriate retcode.

__cache_trait(ad_or_jac_alg)

Return DiffCacheNeeded() or NoDiffCacheNeeded() for an AD backend or BVPJacobianAlgorithm.

__concrete_kwargs(nlsolve, optimize, nlsolve_kwargs, optimize_kwargs[, bvp_verbose])

Select and normalize the keyword arguments forwarded to the active internal nonlinear or optimization solver.

__concrete_solve_algorithm(prob, nlsolve_alg, optimize_alg)

Automatic solver choosing according to the input solver. If none of the solvers are specified, we use nonlinear solvers from NonlinearSolve.jl. If both of the nonlinear solver and optimization solver are specified, we throw an error. If only one of the nonlinear solver and optimization solver is specified, we use that solver.

__construct_internal_problem

Constructs the internal problem according to the specified boundary value problem and the selected algorithm. Depending on the formulation, it returns either a NonlinearProblem or an OptimizationProblem.

__default_coloring_algorithm(diffmode)

Return the sparse matrix coloring algorithm associated with diffmode, or the package default when none is specified.

__default_nonsparse_ad(x_or_type)

Choose the default dense AD backend for an input value or element type.

__default_sparse_ad(x_or_type)

Choose the default sparse AD backend for an input value or element type.

__default_sparsity_detector(diffmode)

Return the sparsity detector associated with diffmode, or the package default when none is specified.

__extract_mesh(u₀, t₀, t₁, n)

Takes the input initial guess and returns the mesh.

__extract_problem_details(prob; kwargs...)

Extract solver setup information from a BVP, including in-place status, state element type, state dimension, subinterval count, and starting state.

__extract_u0(u₀, t₀)

Takes the input initial guess and returns the value at the starting mesh point.

__flatten_initial_guess(u₀) -> Union{AbstractMatrix, AbstractVector, Nothing}

Flattens the initial guess into a matrix. For a function u₀, it returns nothing. For no initial guess, it returns vec(u₀).

__get_bcresid_prototype(prob, u)

Construct the boundary condition residual prototype and its shape metadata for prob.

__get_non_sparse_ad(ad)

Return the dense AD backend inside AutoSparse, or return non-sparse backends unchanged.

__has_initial_guess(u₀) -> Bool

Returns true if the input has an initial guess.

__initial_guess(f, p, t; tune_parameters = false)

Evaluate an initial guess function with the supported (p, t) calling convention.

__initial_guess_length(u₀) -> Int

Returns the length of the initial guess. If the initial guess is a function or no initial guess is supplied, it returns -1.

__initial_guess_on_mesh(u₀, mesh, p, alias_u0::Bool)

Returns the initial guess on the mesh. For DiffEqArray assumes that the mesh is the same as the mesh of the DiffEqArray.

__internal_nlsolve_problem(prob, resid_prototype, u0, args...; kwargs...)

Construct the internal NonlinearProblem or NonlinearLeastSquaresProblem for a BVP discretization.

__internal_optimization_problem(prob, args...; kwargs...)

Construct the internal OptimizationProblem for optimization-based BVP solves.

__internal_solve(prob, alg; kwargs...)

Dispatch to the appropriate solve entry point for internal nonlinear, nonlinear least squares, and optimization problems.

__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.

__maybe_allocate_diffcache(x, chunksize, jac_alg)

Allocate a DiffCache for x when jac_alg requires one; otherwise return x.

__maybe_matmul!(z, A, b, alpha = one(eltype(z)), beta = zero(eltype(z)))

Compute z = alpha * A * b + beta * z, using a fallback loop for array types where mul! is not appropriate.

__needs_diffcache(ad_or_jac_alg) -> Bool

Return whether the AD backend needs a PreallocationTools.DiffCache during residual or Jacobian evaluation.

__resize!(x, n, M)

Resizes the input x to length n and returns the resized array. If n is less than the length of x, it truncates the array. If n is greater than the length of x, it appends zeros to the array.

__restructure_sol(sol, u_size)

Reshape stored solution values to the original non-vector state shape u_size.

__split_kwargs(; abstol, adaptive, controller, verbose = DEFAULT_VERBOSE, kwargs...)

Split BVP solve keywords into cache fields and the keyword set forwarded to internal solvers.

__tunable_part(p)

Return the SciMLStructures tunable portion of p, or p itself for plain parameter containers.

__use_both_error_control(controller) -> Bool

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 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

struct MyCombinedControl <: AbstractErrorControl end

BoundaryValueDiffEqCore.__use_both_error_control(::MyCombinedControl) = true

__vec(x)

Convert scalar, array, or tuple states to a vector representation.

__vec_bc(sol, p, t, bc, u_size)

Call an out-of-place boundary condition on reshaped non-vector state storage and vectorize the result.

__vec_bc!(resid, sol, p, t, bc!, resid_size, u_size)

Call an in-place boundary condition on reshaped non-vector residual and state storage.

__vec_f(u, p, t, f, u_size)

Call an out-of-place problem function on reshaped non-vector state storage and vectorize the result.

__vec_f!(du, u, p, t, f!, u_size)

Call an in-place problem function on reshaped non-vector state storage.

__vec_so_bc(dsol, sol, p, t, bc, u_size)

Call an out-of-place second-order boundary condition on reshaped derivative and state storage and vectorize the result.

__vec_so_bc!(resid, dsol, sol, p, t, bc!, resid_size, u_size)

Call an in-place second-order boundary condition on reshaped derivative and state storage.

_process_verbose_param(verbose) -> BVPVerbosity

Convert supported verbosity presets, booleans, and BVPVerbosity values to the concrete verbosity configuration used by solver caches.

_sparse_like(I, J, x, m = maximum(I), n = maximum(J))

Build a sparse matrix with index storage adapted to x and values shaped like x.

_unwrap_val(x)

Return the value carried by Val(x), or return x unchanged for non-Val inputs.

concrete_jacobian_algorithm(jac_alg, prob, alg)
concrete_jacobian_algorithm(jac_alg, problem_type, prob, alg)

If user provided all the required fields, then return the user provided algorithm. Otherwise, based on the problem type and the algorithm, decide the missing fields.

For example, for TwoPointBVProblem, the bc_diffmode is set to AutoSparse(AutoForwardDiff()) while for StandardBVProblem, the bc_diffmode is set to AutoForwardDiff().

diff!(dx, x)

Write the forward differences of x into dx.

eval_bc_residual(problem_type, bc, sol, p, t)

Evaluate an out-of-place boundary condition residual for standard, two-point, and second-order boundary value problem forms.

eval_bc_residual!(resid, problem_type, bc!, sol, p, t)

Evaluate an in-place boundary condition residual into resid for standard, two-point, and second-order boundary value problem forms.

get_dense_ad(ad)

Return the dense AD backend for AutoSparse wrappers, preserving nothing and dense AD backends unchanged.

interval(mesh, t)

Find the interval that t belongs to in mesh. Assumes that mesh is sorted.

nodual_value(x)

Strip ForwardDiff and SparseConnectivityTracer dual numbers from scalars or arrays.

recursive_flatten(x)

Flatten a vector of array-like states into a single vector.

recursive_flatten!(y, x)

Flatten a vector of array-like states into the preallocated vector y.

recursive_flatten_twopoint!(y, x, sizes)

Flatten a two-point boundary value state vector while preserving the endpoint block sizes.

recursive_unflatten!(y, x)

Copy a flattened vector x back into the array-like storage y.

safe_similar(x, dims...)

Allocate similar(x, dims...) and initialize numeric storage with zeros.