Skip to content

Clarify docs regarding FiveArg() trait #248

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dkarrasch wants to merge 2 commits into
base: master
Choose a base branch
from
+10 −4
Open

Clarify docs regarding FiveArg() trait #248

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
408de8f
Clarify docs regarding `FiveArg()` trait
dkarrasch May 20, 2026
6abfe20
move the note
dkarrasch May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions docs/src/custom.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()

Expand All @@ -117,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
Expand Down Expand Up @@ -172,8 +178,8 @@ 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}`.

# ### Path 2: Invariant `LinearMap` subtypes
Expand Down Expand Up @@ -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.

Expand Down
Loading