fix a lot of docstrings

Author: ChrisRackauckas

src/basic.jl

@@ -1,7 +1,7 @@
 """
 $(TYPEDEF)
 
-Operator representing the identity function `id(u) = u`
+Operator representing the identity function `id(v) = v`
 """
 struct IdentityOperator <: AbstractSciMLOperator{Bool}
     len::Int
@@ -116,7 +116,7 @@ end
 """
 $(TYPEDEF)
 
-Operator representing the null function `n(u) = 0 * u`
+Operator representing the null function `n(v) = 0 * v`
 """
 struct NullOperator <: AbstractSciMLOperator{Bool}
     len::Int
@@ -218,7 +218,7 @@ $TYPEDEF
 
     ScaledOperator
 
-    (λ L)*(u) = λ * L(u)
+    (λ L)*(v) = λ * L(v)
 """
 struct ScaledOperator{T,
     λType,
@@ -417,7 +417,7 @@ end
 """
 Lazy operator addition
 
-    (A1 + A2 + A3...)u = A1*u + A2*u + A3*u ....
+    (A1 + A2 + A3...)v = A1*v + A2*v + A3*v ....
 """
 struct AddedOperator{T,
     O <: Tuple{Vararg{AbstractSciMLOperator}}
@@ -649,10 +649,10 @@ end
 """
     Lazy operator composition
 
-    ∘(A, B, C)(u) = A(B(C(u)))
+    ∘(A, B, C)(v) = A(B(C(v)))
 
     ops = (A, B, C)
-    cache = (B*C*u , C*u)
+    cache = (B*C*v , C*v)
 """
 struct ComposedOperator{T, O, C} <: AbstractSciMLOperator{T}
     """ Tuple of N operators to be applied in reverse"""

src/func.jl

@@ -6,7 +6,7 @@ $(FIELDS)
 """
 mutable struct FunctionOperator{iip, oop, mul5, T <: Number, F, Fa, Fi, Fai, Tr, P, Tt,
     C, iType, oType} <: AbstractSciMLOperator{T}
-    """ Function with signature op(u, p, t) and (if isinplace) op(v, u, p, t) """
+    """ Function with signature op(v, u, p, t) and (if isinplace) op(w, v, u, p, t) """
     op::F
     """ Adjoint operator"""
     op_adjoint::Fa
@@ -134,17 +134,17 @@ $(SIGNATURES)
 Wrap callable object `op` within an `AbstractSciMLOperator`. `op`
 is assumed to have signature
 
-    op(u, p, t; <accepted_kwargs>) -> v
+    op(v, u, p, t; <accepted_kwargs>) -> w
 
 or
 
-    op(v, u, p, t; <accepted_kwargs>) -> [modifies v]
+    op(w, v, u, p, t; <accepted_kwargs>) -> [modifies w]
 
 and optionally
 
-    op(v, u, p, t, α, β; <accepted_kwargs>) -> [modifies v]
+    op(w, v, u, p, t, α, β; <accepted_kwargs>) -> [modifies w]
 
-where `u`, `v` are `AbstractArray`s, `p` is a parameter object, and
+where `u`, `v`, `w` are `AbstractArray`s, `p` is a parameter object, and
 `t`, `α`, `β` are scalars. The first signature corresponds to applying
 the operator with `Base.*`, and the latter two correspond to the
 three-argument, and the five-argument `mul!` respectively.

src/interface.jl

@@ -56,12 +56,12 @@ u = rand(4)
 p = rand(4)
 t = 1.0
 
-# Update the operator and apply it to `u`
+# Update the operator to `(u,p,t)` and apply it to `v`
 L = update_coefficients(L, u, p, t; scale = 2.0)
-result = L * u
+result = L * v
 
 # Or use the interface which separrates the update from the application
-result = L(u, u, p, t; scale = 2.0)
+result = L(v, u, p, t; scale = 2.0)
 ```
 
 """
@@ -96,7 +96,7 @@ p = rand(4)
 t = 1.0
 
 update_coefficients!(L, u, p, t)
-L * u
+L * v
 ```
 
 """
@@ -200,14 +200,14 @@ has_adjoint(L::AbstractSciMLOperator) = false # L', adjoint(L)
 """
 $SIGNATURES
 
-Check if `expmv!(v, L, u, t)`, equivalent to `mul!(v, exp(t * A), u)`, is
-defined for `Number` `t`, and `AbstractArray`s `u, v` of appropriate sizes.
+Check if `expmv!(w, L, v, t)`, equivalent to `mul!(w, exp(t * A), v)`, is
+defined for `Number` `t`, and `AbstractArray`s `w, v` of appropriate sizes.
 """
 has_expmv!(L::AbstractSciMLOperator) = false # expmv!(v, L, t, u)
 """
 $SIGNATURES
 
-Check if `expmv(L, u, t)`, equivalent to `exp(t * A) * u`, is defined for
+Check if `expmv(L, v, t)`, equivalent to `exp(t * A) * v`, is defined for
 `Number` `t`, and `AbstractArray` `u` of appropriate size.
 """
 has_expmv(L::AbstractSciMLOperator) = false # v = exp(L, t, u)
@@ -220,26 +220,26 @@ has_exp(L::AbstractSciMLOperator) = islinear(L)
 """
 $SIGNATURES
 
-Check if `L * u` is defined for `AbstractArray` `u` of appropriate size.
+Check if `L * v` is defined for `AbstractArray` `u` of appropriate size.
 """
 has_mul(L::AbstractSciMLOperator) = true # du = L*u
 """
 $SIGNATURES
 
-Check if `mul!(v, L, u)` is defined for `AbstractArray`s `u, v` of
+Check if `mul!(w, L, v)` is defined for `AbstractArray`s `w, v` of
 appropriate sizes.
 """
 has_mul!(L::AbstractSciMLOperator) = true # mul!(du, L, u)
 """
 $SIGNATURES
 
-Check if `L \\ u` is defined for `AbstractArray` `u` of appropriate size.
+Check if `L \\ v` is defined for `AbstractArray` `v` of appropriate size.
 """
 has_ldiv(L::AbstractSciMLOperator) = false # du = L\u
 """
 $SIGNATURES
 
-Check if `ldiv!(v, L, u)` is defined for `AbstractArray`s `u, v` of
+Check if `ldiv!(w, L, v)` is defined for `AbstractArray`s `w, v` of
 appropriate sizes.
 """
 has_ldiv!(L::AbstractSciMLOperator) = false # ldiv!(du, L, u)

src/matrix.jl

@@ -4,7 +4,7 @@ $SIGNATURES
 
 Represents a linear operator given by an `AbstractMatrix` that may be
 applied to an `AbstractVecOrMat`. Its state is updated by the user-provided
-`update_func` during operator evaluation (`L([v,], u, p, t)`), or by calls
+`update_func` during operator evaluation (`L([w,], v, u, p, t)`), or by calls
 to `update_coefficients[!](L, u, p, t)`. Both recursively call the
 `update_function`, `update_func` which is assumed to have the signature
 
@@ -30,6 +30,7 @@ adjoints, transposes.
 
 Out-of-place update and usage
 ```
+v = rand(4)
 u = rand(4)
 p = rand(4, 4)
 t = rand()
@@ -38,38 +39,39 @@ mat_update = (A, u, p, t; scale = 0.0) -> t * p
 M = MatrixOperator(0.0; update_func = mat_update, accepted_kwargs = (:scale,))
 
 L = M * M + 3I
-L = cache_operator(L, u)
+L = cache_operator(L, v)
 
 # update and evaluate 
-v = L(u, u, p, t; scale = 1.0)
+w = L(v, u, p, t; scale = 1.0)
 
 # In-place evaluation
-w = similar(u)
-L(w, u, u, p, t; scale = 1.0)
+w = similar(v)
+L(w, v, u, p, t; scale = 1.0)
 
 # In-place with scaling
 β = 0.5
-L(w, u, u, p, t, 2.0, β; scale = 1.0) # w = 2.0*(L*u) + 0.5*w
+L(w, v, u, p, t, 2.0, β; scale = 1.0) # w = 2.0*(L*v) + 0.5*w
 ```
 
 In-place update and usage
 ```
+w = zeros(4)
 v = zeros(4)
 u = rand(4)
 p = rand(4) # Must be non-nothing
 t = rand()
 
-mat_update! = (A, u, p, t; scale = 0.0) -> (A .= t * p * p' * scale)
+mat_update! = (A, u, p, t; scale = 0.0) -> (A .= t * p * u' * scale)
 M = MatrixOperator(zeros(4, 4); update_func! = mat_update!, accepted_kwargs = (:scale,))
 L = M * M + 3I
-L = cache_operator(L, u) 
+L = cache_operator(L, v) 
 
 # update L in-place and evaluate
 update_coefficients!(L, u, p, t; scale = 1.0)
-mul!(v, L, u)
+mul!(w, L, v)
 
 # Or use the new interface that separates update and application
-L(v, u, u, p, t; scale = 1.0)
+L(w, v, u, p, t; scale = 1.0)
 ```
 """
 struct MatrixOperator{T, AT <: AbstractMatrix{T}, F, F!} <: AbstractSciMLOperator{T}
@@ -250,16 +252,16 @@ $SIGNATURES
 Represents an elementwise scaling (diagonal-scaling) operation that may
 be applied to an `AbstractVecOrMat`. When `diag` is an `AbstractVector`
 of length N, `L = DiagonalOperator(diag, ...)` can be applied to
-`AbstractArray`s with `size(u, 1) == N`. Each column of the `u` will be
-scaled by `diag`, as in `LinearAlgebra.Diagonal(diag) * u`.
+`AbstractArray`s with `size(u, 1) == N`. Each column of the `v` will be
+scaled by `diag`, as in `LinearAlgebra.Diagonal(diag) * v`.
 
 When `diag` is a multidimensional array, `L = DiagonalOperator(diag, ...)` forms
 an operator of size `(N, N)` where `N = size(diag, 1)` is the leading length of `diag`.
-`L` then is the elementwise-scaling operation on arrays of `length(u) = length(diag)`
+`L` then is the elementwise-scaling operation on arrays of `length(v) = length(diag)`
 with leading length `size(u, 1) = N`.
 
 Its state is updated by the user-provided `update_func` during operator
-evaluation (`L([v,], u, p, t)`), or by calls to
+evaluation (`L([w,], v, u, p, t)`), or by calls to
 `update_coefficients[!](L, u, p, t)`. Both recursively call the
 `update_function`, `update_func` which is assumed to have the signature
 
@@ -446,10 +448,10 @@ end
 """
 $SIGNATURES
 
-Represents a generalized affine operation (`v = A * u + B * b`) that may
+Represents a generalized affine operation (`w = A * v + B * b`) that may
 be applied to an `AbstractVecOrMat`. The user-provided update functions,
 `update_func[!]` update the `AbstractVecOrMat` `b`, and are called
-during operator evaluation (`L([v,], u, p, t)`), or by calls
+during operator evaluation (`L([w,], v, u, p, t)`), or by calls
 to `update_coefficients[!](L, u, p, t)`. The update functions are
 assumed to have the syntax
 
@@ -459,8 +461,8 @@ or
     update_func!(b::AbstractVecOrMat, u ,p , t; <accepted kwargs>) -> [modifies b]
 
 and `B`, `b` are expected to have an appropriate size so that
-`A * u + B * b` makes sense. Specifically, `size(A, 1) == size(B, 1)`, and
-`size(u, 2) == size(b, 2)`.
+`A * v + B * b` makes sense. Specifically, `size(A, 1) == size(B, 1)`, and
+`size(v, 2) == size(b, 2)`.
 
 The set of keyword-arguments accepted by `update_func[!]` must be provided
 to `AffineOperator` via the kwarg `accepted_kwargs` as a tuple of `Symbol`s.
@@ -470,19 +472,20 @@ are not provided.
 # Example
 
 ```
+v = rand(4)
 u = rand(4)
 p = rand(4)
 t = rand()
 
 A = MatrixOperator(rand(4, 4))
 B = MatrixOperator(rand(4, 4))
 
-vec_update_func = (b, u, p, t) -> p * t
+vec_update_func = (b, u, p, t) -> p .* u * t
 L = AffineOperator(A, B, zero(4); update_func = vec_update_func)
-L = cache_operator(M, u)
+L = cache_operator(M, v)
 
 # update L and evaluate
-v = L(u, p, t) # == A * u + B * (p * t)
+w = L(v, u, p, t) # == A * v + B * (p .* u * t)
 ```
 
 """
@@ -532,7 +535,7 @@ end
 """
 $SIGNATURES
 
-Represents the affine operation `v = I * u + I * b`. The update functions,
+Represents the affine operation `w = I * v + I * b`. The update functions,
 `update_func[!]` update the state of `AbstractVecOrMat ` `b`. See
 documentation of `AffineOperator` for more details.
 """
@@ -552,7 +555,7 @@ end
 """
 $SIGNATURES
 
-Represents the affine operation `v = I * u + B * b`. The update functions,
+Represents the affine operation `w = I * v + B * b`. The update functions,
 `update_func[!]` update the state of `AbstractVecOrMat ` `b`. See
 documentation of `AffineOperator` for more details.
 """

src/scalar.jl

@@ -112,7 +112,7 @@ $SIGNATURES
 
 Represents a linear scaling operator that may be applied to a `Number`,
 or an `AbstractArray` subtype. Its state is updated by the user-provided
-`update_func` during operator evaluation (`L([v,] u, p, t)`), or by
+`update_func` during operator evaluation (`L([w,] v, u, p, t)`), or by
 calls to `update_coefficients[!]`. Both recursively call the
 update function, `update_func` which is assumed to have the signature: