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 other completely 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.
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.
- There are a few community forums:
- The #diffeq-bridged and #sciml-bridged channels in the Julia Slack
- JuliaDiffEq on Gitter
- On the Julia Discourse forums (look for the modelingtoolkit tag
- 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`
[38540f10] CommonSolve v0.2.4 `~/work/CommonSolve.jl/CommonSolve.jl`
[e30172f5] Documenter v0.27.24
and using this machine and Julia version.
Julia Version 1.9.1
Commit 147bdf428cd (2023-06-07 08:27 UTC)
Platform Info:
OS: Linux (x86_64-linux-gnu)
CPU: 2 × Intel(R) Xeon(R) Platinum 8171M CPU @ 2.60GHz
WORD_SIZE: 64
LIBM: libopenlibm
LLVM: libLLVM-14.0.6 (ORCJIT, skylake-avx512)
Threads: 1 on 2 virtual cores
A more complete overview of all dependencies and their versions is also provided.
Status `~/work/CommonSolve.jl/CommonSolve.jl/docs/Manifest.toml`
[a4c015fc] ANSIColoredPrinters v0.0.1
[38540f10] CommonSolve v0.2.4 `~/work/CommonSolve.jl/CommonSolve.jl`
[ffbed154] DocStringExtensions v0.9.3
[e30172f5] Documenter v0.27.24
[b5f81e59] IOCapture v0.2.3
[682c06a0] JSON v0.21.4
[69de0a69] Parsers v2.5.10
[aea7be01] PrecompileTools v1.1.2
[21216c6a] Preferences v1.4.0
[2a0f44e3] Base64
[ade2ca70] Dates
[b77e0a4c] InteractiveUtils
[76f85450] LibGit2
[56ddb016] Logging
[d6f4376e] Markdown
[a63ad114] Mmap
[ca575930] NetworkOptions v1.2.0
[de0858da] Printf
[3fa0cd96] REPL
[9a3f8284] Random
[ea8e919c] SHA v0.7.0
[9e88b42a] Serialization
[6462fe0b] Sockets
[fa267f1f] TOML v1.0.3
[8dfed614] Test
[cf7118a7] UUIDs
[4ec0a83e] Unicode