From 408de8fcbe46bb2122daac193aa057d2e9b04aeb Mon Sep 17 00:00:00 2001 From: Daniel Karrasch Date: Wed, 20 May 2026 17:35:01 +0200 Subject: [PATCH 1/2] Clarify docs regarding `FiveArg()` trait --- docs/src/custom.jl | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/src/custom.jl b/docs/src/custom.jl index 160b2bea..5ecc4c32 100644 --- a/docs/src/custom.jl +++ b/docs/src/custom.jl @@ -90,7 +90,8 @@ using BenchmarkTools # `y = zeros(3)`. For that reason, it is beneficial to provide a custom "5-arg # `_unsafe_mul!`" if you can avoid the allocation of an intermediate vector. To indicate # that there exists an allocation-free implementation of multiply-and-add, you should set -# the `MulStyle` trait, whose default is `ThreeArg()`, to `FiveArg()`. +# the `MulStyle` trait, whose default is `ThreeArg()`, to `FiveArg()`. The corresponding +# implementation should then be provided with a 5-argument `LinearMaps._unsafe_mul!`. LinearMaps.MulStyle(A::MyFillMap) = FiveArg() @@ -172,10 +173,15 @@ end MyFillMap(5.0, (3, 4))' * ones(3) -# If you have set the `MulStyle` trait to `FiveArg()`, you should provide a corresponding -# 5-arg `mul!` method for `LinearMaps.TransposeMap{<:Any,<:MyFillMap}` and +# If you have set the `MulStyle` trait to `FiveArg()`, you should provide corresponding +# 5-arg `_unsafe_mul!` methods for `LinearMaps.TransposeMap{<:Any,<:MyFillMap}` and # `LinearMaps.AdjointMap{<:Any,<:MyFillMap}`. +# !!! note +# Note that unlike in the standard library `LinearAlgebra.jl`, there is no automatic +# forwarding of 3-arg `mul!` methods to those with 5 arguments, so you need to define +# the basic 3-arg `_unsafe_mul!` method in any case. + # ### Path 2: Invariant `LinearMap` subtypes # Before we start, let us delete the previously defined method to make sure we use the @@ -227,7 +233,7 @@ mul!(similar(x)', x', A) # `_unsafe_mul!(Y, A::MyFillMap, X::AbstractMatrix)`, and, depending # on the chosen path to handle adjoints/transposes, corresponding methods # for wrapped maps of type `AdjointMap` or `TransposeMap`, plus potentially -# corresponding 5-arg `mul!` methods. This may seem like a lot of methods to +# corresponding 5-arg `_unsafe_mul!` methods. This may seem like a lot of methods to # be implemented, but note that adding such methods is only necessary/recommended # for increased performance. From 6abfe20ad730fdcbc26c561101cc85b84ae29776 Mon Sep 17 00:00:00 2001 From: Daniel Karrasch Date: Wed, 20 May 2026 21:03:21 +0200 Subject: [PATCH 2/2] move the note --- docs/src/custom.jl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/src/custom.jl b/docs/src/custom.jl index 5ecc4c32..3c5cdebc 100644 --- a/docs/src/custom.jl +++ b/docs/src/custom.jl @@ -118,6 +118,11 @@ end # There you go, the allocation is gone and the computation time is significantly reduced. +# !!! note +# Unlike in the standard library `LinearAlgebra.jl`, there is no automatic forwarding +# of 3-arg `mul!` methods to those with 5 arguments, so you need to define the basic +# 3-arg `_unsafe_mul!` method in any case. + # ## Adjoints and transposes # Generically, taking the transpose (or the adjoint) of a (real, resp.) map wraps the @@ -177,11 +182,6 @@ MyFillMap(5.0, (3, 4))' * ones(3) # 5-arg `_unsafe_mul!` methods for `LinearMaps.TransposeMap{<:Any,<:MyFillMap}` and # `LinearMaps.AdjointMap{<:Any,<:MyFillMap}`. -# !!! note -# Note that unlike in the standard library `LinearAlgebra.jl`, there is no automatic -# forwarding of 3-arg `mul!` methods to those with 5 arguments, so you need to define -# the basic 3-arg `_unsafe_mul!` method in any case. - # ### Path 2: Invariant `LinearMap` subtypes # Before we start, let us delete the previously defined method to make sure we use the