GitHub

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 initmust be dispatched on the type defined in your package. For example, do not define a method such as

init(::AbstractVector, ::AlgorithmType)

API

CommonSolve.init — Function
iter = CommonSolve.init(args...; kwargs...)

Creates an iterator or cache object to hold a problem prob and a solver sol to be passed to solve! or step!. 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.

The object returned by init allows more direct control over the internal solving process, and users shouldn't generally need to handle it.

source
CommonSolve.solve — Function
CommonSolve.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...))
source
CommonSolve.solve! — Function
CommonSolve.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.

source
CommonSolve.step! — Function
CommonSolve.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.

source

Contributing

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.5 `~/work/CommonSolve.jl/CommonSolve.jl`
  [e30172f5] Documenter v1.16.1
and using this machine and Julia version.
Julia Version 1.12.3
Commit 966d0af0fdf (2025-12-15 11:20 UTC)
Build Info:
  Official https://julialang.org release
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 4 × AMD EPYC 7763 64-Core Processor
  WORD_SIZE: 64
  LLVM: libLLVM-18.1.7 (ORCJIT, znver3)
  GC: Built with stock GC
Threads: 1 default, 1 interactive, 1 GC (on 4 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
  [1520ce14] AbstractTrees v0.4.5
  [944b1d66] CodecZlib v0.7.8
  [38540f10] CommonSolve v0.2.5 `~/work/CommonSolve.jl/CommonSolve.jl`
  [ffbed154] DocStringExtensions v0.9.5
  [e30172f5] Documenter v1.16.1
  [d7ba0133] Git v1.5.0
  [b5f81e59] IOCapture v1.0.0
  [692b3bcd] JLLWrappers v1.7.1
  [682c06a0] JSON v1.3.0
  [0e77f7df] LazilyInitializedFields v1.3.0
  [d0879d2d] MarkdownAST v0.1.2
  [69de0a69] Parsers v2.8.3
  [aea7be01] PrecompileTools v1.3.3
  [21216c6a] Preferences v1.5.1
  [2792f1a3] RegistryInstances v0.1.0
  [ec057cc2] StructUtils v2.6.0
  [3bb67fe8] TranscodingStreams v0.11.3
  [2e619515] Expat_jll v2.7.3+0
  [020c3dae] Git_LFS_jll v3.7.0+0
  [f8c6e375] Git_jll v2.52.0+0
  [94ce4f54] Libiconv_jll v1.18.0+0
  [9bd350c2] OpenSSH_jll v10.2.1+0
  [0dad84c5] ArgTools v1.1.2
  [56f22d72] Artifacts v1.11.0
  [2a0f44e3] Base64 v1.11.0
  [ade2ca70] Dates v1.11.0
  [f43a241f] Downloads v1.7.0
  [7b1f6079] FileWatching v1.11.0
  [b77e0a4c] InteractiveUtils v1.11.0
  [ac6e5ff7] JuliaSyntaxHighlighting v1.12.0
  [b27032c2] LibCURL v0.6.4
  [76f85450] LibGit2 v1.11.0
  [8f399da3] Libdl v1.11.0
  [56ddb016] Logging v1.11.0
  [d6f4376e] Markdown v1.11.0
  [ca575930] NetworkOptions v1.3.0
  [44cfe95a] Pkg v1.12.1
  [de0858da] Printf v1.11.0
  [3fa0cd96] REPL v1.11.0
  [9a3f8284] Random v1.11.0
  [ea8e919c] SHA v0.7.0
  [9e88b42a] Serialization v1.11.0
  [6462fe0b] Sockets v1.11.0
  [f489334b] StyledStrings v1.11.0
  [fa267f1f] TOML v1.0.3
  [a4e569a6] Tar v1.10.0
  [8dfed614] Test v1.11.0
  [cf7118a7] UUIDs v1.11.0
  [4ec0a83e] Unicode v1.11.0
  [e66e0078] CompilerSupportLibraries_jll v1.3.0+1
  [deac9b47] LibCURL_jll v8.15.0+0
  [e37daf67] LibGit2_jll v1.9.0+0
  [29816b5a] LibSSH2_jll v1.11.3+1
  [14a3606d] MozillaCACerts_jll v2025.5.20
  [458c3c95] OpenSSL_jll v3.5.4+0
  [efcefdf7] PCRE2_jll v10.44.0+1
  [83775a58] Zlib_jll v1.3.1+2
  [8e850ede] nghttp2_jll v1.64.0+1
  [3f19e933] p7zip_jll v17.7.0+0

You can also download the manifest file and the project file.