Document Val approach and add deprecation warnings

This commit makes Val{(...)} the documented and recommended way to
specify accepted_kwargs for zero-allocation kwarg filtering.

Changes:
- Added deprecation warning in preprocess_update_func for plain tuple usage
- Updated all operator docstrings to recommend Val((:kwarg,)) syntax
- Updated examples to use Val approach
- Plain tuples still work but show a deprecation warning (maxlog=1)

The deprecation message clearly explains the migration path and only
shows once per session to avoid spam.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ChrisRackauckas

src/func.jl

@@ -204,7 +204,7 @@ uniform across `op`, `op_adjoint`, `op_inverse`, `op_adjoint_inverse`.
   - `u` - Prototype of the state struct passed to the operator during evaluation, i.e. `L(u, p, t)`. `u` is set to `nothing` if no value is provided.
   - `p` - Prototype of parameter struct passed to the operator during evaluation, i.e. `L(u, p, t)`. `p` is set to `nothing` if no value is provided.
   - `t` - Protype of scalar time variable passed to the operator during evaluation. `t` is set to `zero(T)` if no value is provided.
-  - `accepted_kwargs` - `Tuple` of `Symbol`s corresponding to the keyword arguments accepted by `op*`, and `update_coefficients[!]`. For example, if `op` accepts kwarg `scale`, as in `op(u, p, t; scale)`, then `accepted_kwargs = (:scale,)`.
+  - `accepted_kwargs` - `Val` of a `Tuple` of `Symbol`s for zero-allocation kwarg filtering. Corresponds to the keyword arguments accepted by `op*`, and `update_coefficients[!]`. For example, if `op` accepts kwarg `scale`, as in `op(u, p, t; scale)`, then `accepted_kwargs = Val((:scale,))`. Plain tuples like `(:scale,)` are deprecated but still supported.
   - `T` - `eltype` of the operator. If no value is provided, the constructor inferrs the value from types of `input`, and `output`
   - `isinplace` - `true` if the operator can be used is a mutating way with in-place allocations. This trait is inferred if no value is provided.
   - `outofplace` - `true` if the operator can be used is a non-mutating way with in-place allocations. This trait is inferred if no value is provided.
@@ -451,7 +451,7 @@ function Base.copy(L::FunctionOperator)
         isdefined(L, :p) && L.p !== nothing ? deepcopy(L.p) : nothing,
         L.t,
         L.cache === nothing ? nothing : deepcopy(L.cache),
-        typeof(L).parameters[end-1],  # iType
+        typeof(L).parameters[end - 1],  # iType
         typeof(L).parameters[end]      # oType
     )
 end

src/matrix.jl

@@ -14,8 +14,10 @@ or
 
     update_func!(A::AbstractMatrix, u, p, t; <accepted kwargs>) -> [modifies A]
 
-The set of keyword-arguments accepted by `update_func[!]` must be provided
-to `MatrixOperator` via the kwarg `accepted_kwargs` as a tuple of `Symbol`s.
+The set of keyword-arguments accepted by `update_func[!]` should be provided
+to `MatrixOperator` via the kwarg `accepted_kwargs` as a `Val` of a tuple of `Symbol`s
+for zero-allocation kwarg filtering. For example, `accepted_kwargs = Val((:dtgamma,))`.
+Plain tuples like `(:dtgamma,)` are deprecated but still supported.
 `kwargs` cannot be passed down to `update_func[!]` if `accepted_kwargs`
 are not provided.
 
@@ -38,7 +40,7 @@ p = rand(4, 4)
 t = rand()
 
 mat_update = (A, u, p, t; scale = 0.0) -> t * p
-M = MatrixOperator(0.0; update_func = mat_update, accepted_kwargs = (:scale,))
+M = MatrixOperator(0.0; update_func = mat_update, accepted_kwargs = Val((:scale,)))
 
 L = M * M + 3I
 L = cache_operator(L, v)
@@ -65,7 +67,7 @@ p = rand(4) # Must be non-nothing
 t = rand()
 
 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,))
+M = MatrixOperator(zeros(4, 4); update_func! = mat_update!, accepted_kwargs = Val((:scale,)))
 L = M * M + 3I
 L = cache_operator(L, v) 
 
@@ -291,8 +293,10 @@ or
 
     update_func!(diag::AbstractVecOrMat, u, p, t; <accepted kwargs>) -> [modifies diag]
 
-The set of keyword-arguments accepted by `update_func[!]` must be provided
-to `MatrixOperator` via the kwarg `accepted_kwargs` as a tuple of `Symbol`s.
+The set of keyword-arguments accepted by `update_func[!]` should be provided
+to `DiagonalOperator` via the kwarg `accepted_kwargs` as a `Val` of a tuple of `Symbol`s
+for zero-allocation kwarg filtering. For example, `accepted_kwargs = Val((:dtgamma,))`.
+Plain tuples like `(:dtgamma,)` are deprecated but still supported.
 `kwargs` cannot be passed down to `update_func[!]` if `accepted_kwargs`
 are not provided.
 
@@ -501,8 +505,10 @@ and `B`, `b` are expected to have an appropriate size so that
 `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.
+The set of keyword-arguments accepted by `update_func[!]` should be provided
+to `AffineOperator` via the kwarg `accepted_kwargs` as a `Val` of a tuple of `Symbol`s
+for zero-allocation kwarg filtering. For example, `accepted_kwargs = Val((:dtgamma,))`.
+Plain tuples like `(:dtgamma,)` are deprecated but still supported.
 `kwargs` cannot be passed down to `update_func[!]` if `accepted_kwargs`
 are not provided.
 

src/utils.jl

@@ -18,6 +18,11 @@ function preprocess_update_func(update_func, accepted_kwargs)
     _accepted_kwargs = if accepted_kwargs === nothing
         Val(())
     elseif accepted_kwargs isa Tuple
+        # Deprecation: Encourage users to use Val((...)) directly for better performance
+        @warn """Passing accepted_kwargs as a plain Tuple is deprecated and will be removed in a future version.
+                 Please use Val((...)) instead for zero-allocation kwarg filtering.
+                 Example: accepted_kwargs = Val((:dtgamma,)) instead of accepted_kwargs = (:dtgamma,)
+                 This message will only be shown once per session.""" maxlog=1
         Val(accepted_kwargs)
     else
         accepted_kwargs  # Already a Val or NoKwargFilter