Skip to content

Commit 934f874

Browse files
ChrisRackauckasChrisRackauckas
authored
Merge pull request #38 from SciML/docs
Start real docs
2 parents 4fd9051 + d3daf86 commit 934f874

File tree

7 files changed

+124
-26
lines changed

7 files changed

+124
-26
lines changed

‎LICENSE

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Copyright (c) 2022 SciML
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy
4+
of this software and associated documentation files (the "Software"), to deal
5+
in the Software without restriction, including without limitation the rights
6+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7+
copies of the Software, and to permit persons to whom the Software is
8+
furnished to do so, subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in all
11+
copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19+
SOFTWARE.

‎Project.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,5 +18,6 @@ ArrayInterfaceCore = "0.1"
1818
DiffEqBase = "6"
1919
DocStringExtensions = "0.8, 0.9"
2020
Lazy = "0.15"
21-
Setfield = "1"
21+
Setfield = "0.8, 1"
2222
StaticArrays = "1"
23+
julia = "1.6"

‎docs/pages.jl

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
pages = [
22
"Home" => "index.md",
3-
"Operators" => Any[
4-
"operators/matrix_free_operators.md",
5-
]
3+
"interface.md",
4+
"premade_operators.md"
65
]

‎docs/src/index.md

Lines changed: 25 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,32 @@
1-
# Operator Overview
1+
# SciMLOperators.jl: The SciML Operators Interface
22

3-
The operators in SciMLOperators.jl are instantiations of the `AbstractSciMLOperator`
4-
interface. This is documented in [SciMLBase](https://diffeq.sciml.ai/stable/features/diffeq_operator/). Thus each of the operators
5-
have the functions and traits as defined for the operator interface.
3+
Many functions, from linear solvers to differential equations, require the use of
4+
matrix-free operators in order to achieve maximum performance in many scenarios.
5+
SciMLOperators.jl defines the abstract interface for how operators in the SciML
6+
ecosystem are supposed to be defined. It gives the common set of functions and
7+
traits which solvers can rely on for properly performing their tasks. Along with
8+
that, SciMLOperators.jl provides definitions for the basic standard operators
9+
which are used in building blocks for most tasks, both simplifying the use of operators
10+
while also demonstrating to users how such operators can be built and used in practice.
611

7-
## Operator Compositions
12+
## Why SciMLOperators?
813

9-
Multiplying two DiffEqOperators will build a `DiffEqOperatorComposition`, while
10-
adding two DiffEqOperators will build a `DiffEqOperatorCombination`. Multiplying
11-
a DiffEqOperator by a scalar will produce a `DiffEqScaledOperator`. All
12-
will inherit the appropriate action.
14+
SciMLOperators.jl has the design that is required in order to be used in all scenarios
15+
of equation solvers. For example, Magnus integrators for differential equations
16+
require defining an operator ``u' = A(t)u``, while Munthe-Kaas methods require defining
17+
operators of the form ``u' = A(u)u``. Thus the operators need some form of time and
18+
state dependence which the solvers can update and query when they are non-constant
19+
(`update_coefficients!`). Additionally, the operators need the ability to act like
20+
"normal" functions for equation solvers. For example, if `A(u,p,t)` has the same
21+
operation as `update_coefficients(A,u,p,t); A*u`, then `A` can be used in any place where
22+
a differential equation definition `f(u,p,t)` is used without requring the user or solver
23+
to do any extra work.
1324

14-
### Efficiency of Composed Operator Actions
15-
16-
Composed operator actions utilize NNLib.jl in order to do cache-efficient
17-
convolution operations in higher-dimensional combinations.
25+
Thus while previous good efforts for matrix-free operators have existed in the Julia ecosystem,
26+
such as [LinearMaps.jl](https://github.com/JuliaLinearAlgebra/LinearMaps.jl), those operator
27+
interfaces lack these aspects in order to actually be fully seamless with downstream equation
28+
solvers. This necessitates the definition and use of an extended operator interface with all
29+
of these properties, hence the `AbstractSciMLOperator` interface.
1830

1931
## Contributing
2032

‎docs/src/interface.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# The AbstractSciMLOperator Interface
2+
3+
## Formal Properties of DiffEqOperators
4+
5+
These are the formal properties that an `AbstractSciMLOperator` should obey
6+
for it to work in the solvers.
7+
8+
## AbstractDiffEqOperator Interface Description
9+
10+
1. Function call and multiplication: `L(du,u,p,t)` for inplace and `du = L(u,p,t)` for
11+
out-of-place, meaning `L*u` and `mul!`.
12+
2. If the operator is not a constant, update it with `(u,p,t)`. A mutating form, i.e.
13+
`update_coefficients!(A,u,p,t)` that changes the internal coefficients, and a
14+
out-of-place form `B = update_coefficients(A,u,p,t)`.
15+
3. `isconstant(A)` trait for whether the operator is constant or not.
16+
17+
## AbstractDiffEqLinearOperator Interface Description
18+
19+
1. `AbstractSciMLLinearOperator <: AbstractSciMLOperator`
20+
2. Can absorb under multiplication by a scalar. In all algorithms things like
21+
`dt*L` show up all the time, so the linear operator must be able to absorb
22+
such constants.
23+
4. `isconstant(A)` trait for whether the operator is constant or not.
24+
5. Optional: `diagonal`, `symmetric`, etc traits from LinearMaps.jl.
25+
6. Optional: `exp(A)`. Required for simple exponential integration.
26+
7. Optional: `expv(A,u,t) = exp(t*A)*u` and `expv!(v,A::AbstractSciMLOperator,u,t)`
27+
Required for sparse-saving exponential integration.
28+
8. Optional: factorizations. `ldiv!`, `factorize` et. al. This is only required
29+
for algorithms which use the factorization of the operator (Crank-Nicolson),
30+
and only for when the default linear solve is used.
31+
32+
## Note About Affine Operators
33+
34+
Affine operators are operators which have the action `Q*x = A*x + b`. These operators have
35+
no matrix representation, since if there was it would be a linear operator instead of an
36+
affine operator. You can only represent an affine operator as a linear operator in a
37+
dimension of one larger via the operation: `[A b] * [u;1]`, so it would require something modified
38+
to the input as well. As such, affine operators are a distinct generalization of linear operators.
39+
40+
While it this seems like it might doom the idea of using matrix-free affine operators, it turns out
41+
that affine operators can be used in all cases where matrix-free linear solvers are used due to
42+
an easy genearlization of the standard convergence proofs. If Q is the affine operator
43+
``Q(x) = Ax + b``, then solving ``Qx = c`` is equivalent to solving ``Ax + b = c`` or ``Ax = c-b``.
44+
If you know do this same "plug-and-chug" handling of the affine operator in into the GMRES/CG/etc.
45+
convergence proofs, move the affine part to the rhs residual, and show it converges to solving
46+
``Ax = c-b``, and thus GMRES/CG/etc. solves ``Q(x) = c`` for an affine operator properly.
47+
48+
That same trick then can be used pretty much anywhere you would've had a linear operator to extend
49+
the proof to affine operators, so then ``exp(A*t)*v`` operations via Krylov methods work for A being
50+
affine as well, and all sorts of things. Thus affine operators have no matrix representation but they
51+
are still compatible with essentially any Krylov method which would otherwise be compatible with
52+
matrix-free representations, hence their support in the SciMLOperators interface.

‎docs/src/operators/matrix_free_operators.md

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/src/premade_operators.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Premade SciMLOperators
2+
3+
## Direct Operator Definitions
4+
5+
```@docs
6+
ScalarOperator
7+
SciMLOperators.NullOperator
8+
MatrixOperator
9+
DiagonalOperator
10+
AffineOperator
11+
FunctionOperator
12+
```
13+
14+
## Lazy Operator Compositions
15+
16+
```@docs
17+
SciMLOperators.ScaledOperator
18+
SciMLOperators.ComposedOperator
19+
SciMLOperators.AddedOperator
20+
SciMLOperators.InvertedOperator
21+
SciMLOperators.InvertibleOperator
22+
SciMLOperators.AdjointedOperator
23+
SciMLOperators.TransposedOperator
24+
```

0 commit comments

Comments
 (0)