CommonSolve.jl: The Common Solve Definition and Interface
This holds the common solve
, init
, solve!
, and step!
commands. By using the same definition, solver libraries from entirely different ecosystems can extend the functions and thus not clash with SciML if both ecosystems export the solve
command. The rules are that you must dispatch on one of your own types. That's it. No pirates.
Installation
To install CommonSolve.jl, use the Julia package manager:
using Pkg
Pkg.add("CommonSolve")
General recommendation
solve
function has the default definition
solve(args...; kwargs...) = solve!(init(args...; kwargs...))
So, we recommend defining
init(::ProblemType, args...; kwargs...) :: SolverType
solve!(::SolverType) :: SolutionType
where ProblemType
, SolverType
, and SolutionType
are the types defined in your package.
In many cases, the SolverType
is an object that is iteratively progressed to achieve the solution. In such cases, the step!
function can be used:
step!(::SolverType, args...; kwargs...)
To avoid method ambiguity, the first argument of solve
, solve!
, step!
, and init
must be dispatched on the type defined in your package. For example, do not define a method such as
init(::AbstractVector, ::AlgorithmType)
API
CommonSolve.init
— Functioniter = CommonSolve.init(args...; kwargs...)
Solves an equation or other mathematical problem using the algorithm specified in the arguments. Generally, the interface is:
iter = CommonSolve.init(prob::ProblemType,alg::SolverType; kwargs...)::IterType
-CommonSolve.solve!(iter)::SolutionType
where the keyword arguments are uniform across all choices of algorithms. The iter
type will be different for the different problem types.
CommonSolve.solve
— FunctionCommonSolve.solve(args...; kwargs...)
Solves an equation or other mathematical problem using the algorithm specified in the arguments. Generally, the interface is:
CommonSolve.solve(prob::ProblemType,alg::SolverType; kwargs...)::SolutionType
where the keyword arguments are uniform across all choices of algorithms.
By default, solve
defaults to using solve!
on the iterator form, i.e.:
solve(args...; kwargs...) = solve!(init(args...; kwargs...))
CommonSolve.solve!
— FunctionCommonSolve.solve!(iter)
Solves an equation or other mathematical problem using the algorithm specified in the arguments. Generally, the interface is:
iter = CommonSolve.init(prob::ProblemType,alg::SolverType; kwargs...)::IterType
-CommonSolve.solve!(iter)::SolutionType
where the keyword arguments are uniform across all choices of algorithms. The iter
type will be different for the different problem types.
CommonSolve.step!
— FunctionCommonSolve.step!(iter, args...; kwargs...)
Progress the iterator object (the one returned by CommonSolve.init
). The additional arguments typically describe how much to progress the iterator for, and are implementation-specific.
Contributing
Please refer to the SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages for guidance on PRs, issues, and other matters relating to contributing to SciML.
See the SciML Style Guide for common coding practices and other style decisions.
There are a few community forums:
- The #diffeq-bridged and #sciml-bridged channels in the Julia Slack
- The #diffeq-bridged and #sciml-bridged channels in the Julia Zulip
- On the Julia Discourse forums
- See also SciML Community page
Reproducibility
The documentation of this SciML package was built using these direct dependencies,
Status `~/work/CommonSolve.jl/CommonSolve.jl/docs/Project.toml`
+CommonSolve.solve!(iter)::SolutionType
where the keyword arguments are uniform across all choices of algorithms. The iter
type will be different for the different problem types.