GitHub

SciMLOperators.jl: Unified operator interface for SciML.ai and beyond

SciMLOperators is a package for managing linear, nonlinear, time-dependent, and parameter dependent operators acting on vectors, (or column-vectors of matrices). We provide wrappers for matrix-free operators, fast tensor-product evaluations, pre-cached mutating evaluations, as well as Zygote-compatible non-mutating evaluations.

The lazily implemented operator algebra allows the user to update the operator state by passing in an update function that accepts arbitrary parameter objects. Further, our operators behave like AbstractMatrix types thanks to overloads defined for methods in Base, and LinearAlgebra.

Therefore, an AbstractSciMLOperator can be passed to LinearSolve.jl, or NonlinearSolve.jl as a linear or nonlinear operator, or to OrdinaryDiffEq.jl as an ODEFunction. Examples of usage within the SciML ecosystem are provided in the documentation.

Installation

To install SciMLOperators.jl, use the Julia package manager:

using Pkg
Pkg.add("SciMLOperators")

Examples

Let M, D, F be matrix-based, diagonal-matrix-based, and function-based SciMLOperators respectively.

N = 4
f = (u, p, t) -> u .* u

M = MatrixOperator(rand(N, N))
D = DiagonalOperator(rand(N))
F = FunctionOperator(f, zeros(N), zeros(N))

Then, the following codes just work.

L1 = 2M + 3F + LinearAlgebra.I + rand(N, N)
L2 = D * F * M'
L3 = kron(M, D, F)
L4 = M \ D
L5 = [M; D]' * [M F; F D] * [F; D]

Each L# can be applied to AbstractVectors of appropriate sizes:

p = nothing # parameter struct
t = 0.0     # time

u = rand(N)
v = L1(u, p, t) # == L1 * u

u_kron = rand(N^3)
v_kron = L3(u_kron, p, t) # == L3 * u_kron

For mutating operator evaluations, call cache_operator to generate an in-place cache, so the operation is nonallocating.

α, β = rand(2)

# allocate cache
L2 = cache_operator(L2, u)
L4 = cache_operator(L4, u)

# allocation-free evaluation
L2(v, u, p, t) # == mul!(v, L2, u)
L4(v, u, p, t, α, β) # == mul!(v, L4, u, α, β)

The calling signature L(u, p, t), for out-of-place evaluations, is equivalent to L * u, and the in-place evaluation L(v, u, p, t, args...) is equivalent to LinearAlgebra.mul!(v, L, u, args...), where the arguments p, t are passed to L to update its state. More details are provided in the operator update section below. While overloads to Base.* and LinearAlgebra.mul! are available, where a SciMLOperator behaves like an AbstractMatrix, we recommend sticking with the L(u, p, t), L(v, u, p, t), L(v, u, p, t, α, β) calling signatures as the latter internally update the operator state.

The (u, p, t) calling signature is standardized over the SciML ecosystem and is flexible enough to support use cases such as time-evolution in ODEs, as well as sensitivity computation with respect to the parameter object p.

Features

  • Matrix-free operators with FunctionOperator
  • Fast tensor product evaluation with TensorProductOperator
  • Lazy algebra: addition, subtraction, multiplication, inverse, adjoint, and transpose
  • Couple fast methods for operator evaluation with inversion via InvertibleOperator
  • One-line API to update operator state depending on arbitrary parameters.
  • Mutating and nonmutating update behavior (Zygote compatible)
  • One-line API for pre-caching operators for in-place operator evaluations

Contributing

Reproducibility

The documentation of this SciML package was built using these direct dependencies,
Status `~/work/SciMLOperators.jl/SciMLOperators.jl/docs/Project.toml`
  [e30172f5] Documenter v1.2.1
  [7a1cc6ca] FFTW v1.8.0
  [c0aeaf25] SciMLOperators v0.3.8 `~/work/SciMLOperators.jl/SciMLOperators.jl`
and using this machine and Julia version.
Julia Version 1.10.1
Commit 7790d6f0641 (2024-02-13 20:41 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
  LIBM: libopenlibm
  LLVM: libLLVM-15.0.7 (ORCJIT, znver3)
Threads: 1 default, 0 interactive, 1 GC (on 4 virtual cores)
A more complete overview of all dependencies and their versions is also provided.
Status `~/work/SciMLOperators.jl/SciMLOperators.jl/docs/Manifest.toml`
  [a4c015fc] ANSIColoredPrinters v0.0.1
  [621f4979] AbstractFFTs v1.5.0
  [1520ce14] AbstractTrees v0.4.5
  [79e6a3ab] Adapt v4.0.1
  [4fba245c] ArrayInterface v7.7.1
  [187b0558] ConstructionBase v1.5.4
  [ffbed154] DocStringExtensions v0.9.3
  [e30172f5] Documenter v1.2.1
  [7a1cc6ca] FFTW v1.8.0
  [d7ba0133] Git v1.3.1
  [b5f81e59] IOCapture v0.2.4
  [692b3bcd] JLLWrappers v1.5.0
  [682c06a0] JSON v0.21.4
  [0e77f7df] LazilyInitializedFields v1.2.2
  [1914dd2f] MacroTools v0.5.13
  [d0879d2d] MarkdownAST v0.1.2
  [69de0a69] Parsers v2.8.1
  [aea7be01] PrecompileTools v1.2.0
  [21216c6a] Preferences v1.4.1
  [189a3867] Reexport v1.2.2
  [2792f1a3] RegistryInstances v0.1.0
  [ae029012] Requires v1.3.0
  [c0aeaf25] SciMLOperators v0.3.8 `~/work/SciMLOperators.jl/SciMLOperators.jl`
  [efcf1570] Setfield v1.1.1
  [1e83bf80] StaticArraysCore v1.4.2
  [2e619515] Expat_jll v2.5.0+0
  [f5851436] FFTW_jll v3.3.10+0
  [f8c6e375] Git_jll v2.44.0+0
  [1d5cc7b8] IntelOpenMP_jll v2024.0.2+0
  [94ce4f54] Libiconv_jll v1.17.0+0
  [856f044c] MKL_jll v2024.0.0+0
  [458c3c95] OpenSSL_jll v3.0.13+0
  [0dad84c5] ArgTools v1.1.1
  [56f22d72] Artifacts
  [2a0f44e3] Base64
  [ade2ca70] Dates
  [f43a241f] Downloads v1.6.0
  [7b1f6079] FileWatching
  [9fa8497b] Future
  [b77e0a4c] InteractiveUtils
  [4af54fe1] LazyArtifacts
  [b27032c2] LibCURL v0.6.4
  [76f85450] LibGit2
  [8f399da3] Libdl
  [37e2e46d] LinearAlgebra
  [56ddb016] Logging
  [d6f4376e] Markdown
  [a63ad114] Mmap
  [ca575930] NetworkOptions v1.2.0
  [44cfe95a] Pkg v1.10.0
  [de0858da] Printf
  [3fa0cd96] REPL
  [9a3f8284] Random
  [ea8e919c] SHA v0.7.0
  [9e88b42a] Serialization
  [6462fe0b] Sockets
  [2f01184e] SparseArrays v1.10.0
  [4607b0f0] SuiteSparse
  [fa267f1f] TOML v1.0.3
  [a4e569a6] Tar v1.10.0
  [8dfed614] Test
  [cf7118a7] UUIDs
  [4ec0a83e] Unicode
  [e66e0078] CompilerSupportLibraries_jll v1.1.0+0
  [deac9b47] LibCURL_jll v8.4.0+0
  [e37daf67] LibGit2_jll v1.6.4+0
  [29816b5a] LibSSH2_jll v1.11.0+1
  [c8ffd9c3] MbedTLS_jll v2.28.2+1
  [14a3606d] MozillaCACerts_jll v2023.1.10
  [4536629a] OpenBLAS_jll v0.3.23+4
  [efcefdf7] PCRE2_jll v10.42.0+1
  [bea87d4a] SuiteSparse_jll v7.2.1+1
  [83775a58] Zlib_jll v1.2.13+1
  [8e850b90] libblastrampoline_jll v5.8.0+1
  [8e850ede] nghttp2_jll v1.52.0+1
  [3f19e933] p7zip_jll v17.4.0+2

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