extend docs

Author: dkarrasch

docs/src/custom.jl

@@ -73,7 +73,7 @@ mul!(ones(3,3), A, reshape(collect(1:9), 3, 3), 2, 2)
 using BenchmarkTools
 
 @benchmark mul!($(zeros(3)), $A, $x)
- 
+
 #-
 
 @benchmark mul!($(zeros(3)), $A, $x, $(rand()), $(rand()))
@@ -241,6 +241,9 @@ mul!(similar(x)', x', A)
 F = MyFillMap(5, (100,100))
 M = Matrix{eltype(F)}(undef, size(F))
 @benchmark Matrix($F)
+
+#-
+
 @benchmark LinearMaps._unsafe_mul!($(Matrix{Int}(undef, (100,100))), $(MyFillMap(5, (100,100))), true)
 
 # If a more performant implementation exists, it is recommended to overwrite this method,
@@ -249,6 +252,9 @@ M = Matrix{eltype(F)}(undef, size(F))
 
 LinearMaps._unsafe_mul!(M::AbstractMatrix, A::MyFillMap, s::Number) = fill!(M, A.λ*s)
 @benchmark Matrix($F)
+
+#-
+
 @benchmark LinearMaps._unsafe_mul!($(Matrix{Int}(undef, (100,100))), $(MyFillMap(5, (100,100))), true)
 
 # As one can see, the above runtimes are dominated by the allocation of the output matrix,
@@ -259,16 +265,18 @@ LinearMaps._unsafe_mul!(M::AbstractMatrix, A::MyFillMap, s::Number) = fill!(M, A
 
 # As usual, generic fallbacks for `LinearMap` slicing exist and are handled by the following
 # method hierarchy, where at least one of `I` and `J` has to be a `Colon`:
-# 
+#
 #     Base.getindex(::LinearMap, I, J)
 #     -> LinearMaps._getindex(::LinearMap, I, J)
-# 
+#
 # The method `Base.getindex` checks the validity of the the requested indices and calls
 # `LinearMaps._getindex`, which should be overloaded for custom `LinearMap`s subtypes.
 # For instance:
 
 @benchmark F[1,:]
 
+#-
+
 LinearMaps._getindex(A::MyFillMap, ::Integer, J::Base.Slice) = fill(A.λ, axes(J))
 @benchmark F[1,:]
 

docs/src/types.md

@@ -143,3 +143,13 @@ as in the usual matrix case: `transpose(A) * x` and `mul!(y, A', x)`, for instan
   purposes or if you want to have the explicit sparse matrix representation of
   a linear map for which you only have a function definition (e.g. to be able
   to use its `transpose` or `adjoint`).
+
+### Slicing methods
+
+Complete slicing, i.e., `A[:,j]`, `A[:,J]`, `A[i,:]`, `A[I,:]` and `A[:,:]` for `i`, `j`
+`Integer` and `I,J` `AbstractVector{<:Integer}` is generically available for any
+`A::LinearMap` subtype via application of `A` (or `A'` for (predominantly) horizontal
+slicing) to standard unit vectors of appropriate length. By complete slicing we refer
+two-dimensional Cartesian indexing where at least one of the "indices" is a colon. This is
+facilitated by overloads of `Base.getindex`. Partial slicing à la `A[I,J]` and scalar or
+linear indexing are _not_ supported for performance reasons.