diff --git a/Project.toml b/Project.toml index a94b37f..6489d7d 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "FactoredMatrices" uuid = "13d07ad6-c0d4-11e8-35b1-91a532e61cc8" authors = ["Tim Holy "] -version = "0.1.2" +version = "0.1.3" [deps] LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" diff --git a/src/FactoredMatrices.jl b/src/FactoredMatrices.jl index 2301c53..cbe2285 100644 --- a/src/FactoredMatrices.jl +++ b/src/FactoredMatrices.jl @@ -5,89 +5,203 @@ import Base: *, Array, size, length, getindex, similar, adjoint, transpose import LinearAlgebra: mul!, dot export FactoredMatrix +VERSION >= v"1.11" && eval(Meta.parse("public Workspace")) -# For multiplication against a matrix with J columns, or by a matrix with J rows """ -Store `M` as `U*V` and use it for computations. -This type is tailored to multiply against matrices of pre-determined size; -it maintains temporary buffers to avoid the need to allocate intermediate storage -when exploiting the factored representation. - -Constructor syntax: - FactoredMatrix(U, V, J::Integer) -where you expect to compute `M*C` for `C` with `J` columns, `D*M` with `J` rows, -or any similar conjugate/transpose operations. + FactoredMatrix(U, V) + +Store the matrix `M = U*V` in factored form for efficient computation. +Multiplications exploit the factored structure without forming the full dense matrix. + +For allocation-free repeated multiplications, create a [`Workspace`](@ref) and pass it +as `mul!(C, A, B; cache=ws)`. """ struct FactoredMatrix{T} <: Factorization{T} - U::Matrix{T} # M x K - V::Matrix{T} # K x N - temp::Matrix{T} # K x J - tempT::Matrix{T} # J x K - - function FactoredMatrix{T}(U::Matrix{T}, V::Matrix{T}, J::Int) where T - K = size(U, 2) - size(V, 1) == K || throw(DimensionMismatch("U and V must be able to be multiplied")) - temp = similar(U, K, J) - tempT = similar(U, J, K) - new{T}(U, V, temp, tempT) + U::Matrix{T} # m × k + V::Matrix{T} # k × n + + function FactoredMatrix{T}(U::Matrix{T}, V::Matrix{T}) where T + # This deliberately requires `Matrix{T}` to ensure these precise buffers will be used + size(U, 2) == size(V, 1) || + throw(DimensionMismatch("U is $(size(U,1))×$(size(U,2)) but V is $(size(V,1))×$(size(V,2))")) + new{T}(U, V) end end -FactoredMatrix(U::Matrix{T}, V::Matrix{T}, J::Integer) where {T} = FactoredMatrix{T}(U, V, Int(J)) +FactoredMatrix(U::Matrix{T}, V::Matrix{T}) where T = FactoredMatrix{T}(U, V) + +function FactoredMatrix(U::Matrix{T}, V::Matrix{T}, ::Integer) where T + Base.depwarn( + "FactoredMatrix(U, V, j) is deprecated; use FactoredMatrix(U, V) and " * + "create a Workspace(fm, j) for allocation-free mul!", + :FactoredMatrix) + FactoredMatrix{T}(U, V) +end + +""" + Workspace(A::FactoredMatrix, j::Integer) + +Pre-allocated scratch buffers for allocation-free `mul!` with a [`FactoredMatrix`](@ref). +`j` is the number of columns (or rows) in the non-`FactoredMatrix` operand. + +Create a separate `Workspace` per thread when multiplying concurrently against the same `A`. + +# Example +```julia +ws = Workspace(A, size(B, 2)) +mul!(C, A, B; cache=ws) # writes C = A*B with no allocation +``` +""" +struct Workspace{T} + temp::Matrix{T} # k × j: intermediate for (left FM or its adjoint/transpose) × B + tempT::Matrix{T} # j × k: intermediate for A × (right FM or its adjoint/transpose) +end -size(A::FactoredMatrix) = size(A.U,1), size(A.V,2) -size(A::FactoredMatrix, d::Integer) = d == 1 ? size(A.U,1) : (d == 2 ? size(A.V,2) : 1) +function Workspace(A::FactoredMatrix{T}, j::Integer) where T + k = size(A.U, 2) + j = Int(j) + Workspace{T}(Matrix{T}(undef, k, j), Matrix{T}(undef, j, k)) +end + +size(A::FactoredMatrix) = size(A.U, 1), size(A.V, 2) +size(A::FactoredMatrix, d::Integer) = d == 1 ? size(A.U, 1) : (d == 2 ? size(A.V, 2) : 1) similar(A::FactoredMatrix, dims) = Array{eltype(A.U)}(undef, dims) similar(A::FactoredMatrix, T, dims) = Array{T}(undef, dims) -length(A::FactoredMatrix) = size(A.U,1)*size(A.V,2) +length(A::FactoredMatrix) = size(A.U, 1) * size(A.V, 2) -Array(A::FactoredMatrix) = A.U*A.V +Array(A::FactoredMatrix) = A.U * A.V adjoint(A::FactoredMatrix) = Adjoint(A) -getindex(A::Adjoint{T,FactoredMatrix{T}},i,j) where T = - um(A.parent.U[j,:].*A.parent.V[:,i])' transpose(A::FactoredMatrix) = Transpose(A) -getindex(A::Transpose{T,FactoredMatrix{T}},i,j) where T = +getindex(A::Adjoint{T,FactoredMatrix{T}}, i, j) where T = + conj(sum(A.parent.U[j,:] .* A.parent.V[:,i])) +getindex(A::Transpose{T,FactoredMatrix{T}}, i, j) where T = sum(A.parent.U[j,:] .* A.parent.V[:,i]) -mul!(C, A::FactoredMatrix, B::FactoredMatrix) = error("not defined") -mul!(C, A::FactoredMatrix, B) = mul!(C, A.U, mul!(A.temp, A.V, B)) -mul!(C, A::FactoredMatrix, b::AbstractVector) = mul!(C, A.U, mul!(view(A.temp, :, 1), A.V, b)) -mul!(C, A, B::FactoredMatrix) = mul!(C, mul!(B.tempT, A, B.U), B.V) -mul!(C, A::Transpose{T,FactoredMatrix{T}}, B::FactoredMatrix) where T = error("not defined") -mul!(C::Array{T,N}, A::Transpose{T,FactoredMatrix{T}}, B::Array{T,N}) where {T,N} = - mul!(C, transpose(A.parent.V), mul!(A.parent.temp, transpose(A.parent.U), B)) -mul!(C, A::Transpose, B::FactoredMatrix) = mul!(C, mul!(B.tempT, A, B.U), B.V) -mul!(C, A::Adjoint{T,FactoredMatrix{T}}, B::FactoredMatrix) where T = error("not defined") -mul!(C::Array{T,N}, A::Adjoint{T,FactoredMatrix{T}}, B::Array{T,N}) where {T,N} = - mul!(C, A.parent.V', mul!(A.parent.temp, A.parent.U', B)) -mul!(C, A::Adjoint, B::FactoredMatrix) = mul!(C, mul!(B.tempT, A, B.U), B.V) -mul!(C, A::FactoredMatrix, B::Transpose{T,FactoredMatrix{T}}) where T = error("not defined") -mul!(C, A::FactoredMatrix, B::Transpose) = mul!(C, A.U, mul!(A.temp, A.V, B)) -mul!(C::Array{T,N}, A::Array{T,N}, B::Transpose{T,FactoredMatrix{T}}) where {T,N} = - mul!(C, mul!(B.parent.tempT, A, transpose(B.parent.V)), transpose(B.parent.U)) -mul!(C, A::FactoredMatrix, B::Adjoint{T,FactoredMatrix{T}}) where T = error("not defined") -mul!(C, A::FactoredMatrix, B::Adjoint) = mul!(C, A.U, mul!(A.temp, A.V, B)) -mul!(C::Array{T,N}, A::Array{T,N}, B::Adjoint{T,FactoredMatrix{T}}) where {T,N} = - mul!(C, mul!(B.parent.tempT, A, B.parent.V'), B.parent.U') +# --- mul! --- + +mul!(C, A::FactoredMatrix, B::FactoredMatrix; cache::Union{Nothing,Workspace}=nothing) = + error("not defined") + +function mul!(C, A::FactoredMatrix, B; cache::Union{Nothing,Workspace}=nothing) + if cache === nothing + mul!(C, A.U, A.V * B) + else + mul!(C, A.U, mul!(cache.temp, A.V, B)) + end +end + +function mul!(C, A::FactoredMatrix, b::AbstractVector; cache::Union{Nothing,Workspace}=nothing) + if cache === nothing + mul!(C, A.U, A.V * b) + else + mul!(C, A.U, mul!(view(cache.temp, :, 1), A.V, b)) + end +end + +function mul!(C, A, B::FactoredMatrix; cache::Union{Nothing,Workspace}=nothing) + if cache === nothing + mul!(C, A * B.U, B.V) + else + mul!(C, mul!(cache.tempT, A, B.U), B.V) + end +end + +mul!(C, A::Transpose{T,FactoredMatrix{T}}, B::FactoredMatrix; cache::Union{Nothing,Workspace}=nothing) where T = + error("not defined") + +function mul!(C::Array{T,N}, A::Transpose{T,FactoredMatrix{T}}, B::Array{T,N}; + cache::Union{Nothing,Workspace}=nothing) where {T,N} + if cache === nothing + mul!(C, transpose(A.parent.V), transpose(A.parent.U) * B) + else + mul!(C, transpose(A.parent.V), mul!(cache.temp, transpose(A.parent.U), B)) + end +end + +function mul!(C, A::Transpose, B::FactoredMatrix; cache::Union{Nothing,Workspace}=nothing) + if cache === nothing + mul!(C, A * B.U, B.V) + else + mul!(C, mul!(cache.tempT, A, B.U), B.V) + end +end + +mul!(C, A::Adjoint{T,FactoredMatrix{T}}, B::FactoredMatrix; cache::Union{Nothing,Workspace}=nothing) where T = + error("not defined") + +function mul!(C::Array{T,N}, A::Adjoint{T,FactoredMatrix{T}}, B::Array{T,N}; + cache::Union{Nothing,Workspace}=nothing) where {T,N} + if cache === nothing + mul!(C, A.parent.V', A.parent.U' * B) + else + mul!(C, A.parent.V', mul!(cache.temp, A.parent.U', B)) + end +end + +function mul!(C, A::Adjoint, B::FactoredMatrix; cache::Union{Nothing,Workspace}=nothing) + if cache === nothing + mul!(C, A * B.U, B.V) + else + mul!(C, mul!(cache.tempT, A, B.U), B.V) + end +end + +mul!(C, A::FactoredMatrix, B::Transpose{T,FactoredMatrix{T}}; cache::Union{Nothing,Workspace}=nothing) where T = + error("not defined") + +function mul!(C, A::FactoredMatrix, B::Transpose; cache::Union{Nothing,Workspace}=nothing) + if cache === nothing + mul!(C, A.U, A.V * B) + else + mul!(C, A.U, mul!(cache.temp, A.V, B)) + end +end + +function mul!(C::Array{T,N}, A::Array{T,N}, B::Transpose{T,FactoredMatrix{T}}; + cache::Union{Nothing,Workspace}=nothing) where {T,N} + if cache === nothing + mul!(C, A * transpose(B.parent.V), transpose(B.parent.U)) + else + mul!(C, mul!(cache.tempT, A, transpose(B.parent.V)), transpose(B.parent.U)) + end +end + +mul!(C, A::FactoredMatrix, B::Adjoint{T,FactoredMatrix{T}}; cache::Union{Nothing,Workspace}=nothing) where T = + error("not defined") + +function mul!(C, A::FactoredMatrix, B::Adjoint; cache::Union{Nothing,Workspace}=nothing) + if cache === nothing + mul!(C, A.U, A.V * B) + else + mul!(C, A.U, mul!(cache.temp, A.V, B)) + end +end + +function mul!(C::Array{T,N}, A::Array{T,N}, B::Adjoint{T,FactoredMatrix{T}}; + cache::Union{Nothing,Workspace}=nothing) where {T,N} + if cache === nothing + mul!(C, A * B.parent.V', B.parent.U') + else + mul!(C, mul!(cache.tempT, A, B.parent.V'), B.parent.U') + end +end + +# --- * (allocating) --- *(A::FactoredMatrix, B::FactoredMatrix) = error("not defined") -*(A::FactoredMatrix, B) = - mul!(Array{promote_type(eltype(A),eltype(B))}(undef, (size(A,1), size(B,2))), A, B) -*(A, B::FactoredMatrix) = - mul!(Array{promote_type(eltype(A),eltype(B))}(undef, (size(A,1), size(B,2))), A, B) +*(A::FactoredMatrix, B) = A.U * (A.V * B) +*(A, B::FactoredMatrix) = (A * B.U) * B.V + +# --- Queries --- function LinearAlgebra.issymmetric(A::FactoredMatrix) - if size(A.U,1) != size(A.V,2) || size(A.U,2) != size(A.V,1) - return false - end - A.U == A.V' + size(A.U, 1) == size(A.V, 2) && A.U == A.V' end -# For computing sum-of-squared difference between two FactoredMatrixes function dot(A::FactoredMatrix, B::FactoredMatrix) - M1 = B.U'*A.U - M2 = B.V*A.V' - sum(M1.*conj(M2)) + M1 = B.U' * A.U + M2 = B.V * A.V' + sum(M1 .* conj(M2)) end """ diff --git a/test/runtests.jl b/test/runtests.jl index 2c09d99..baa796b 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -4,21 +4,36 @@ using FactoredMatrices myrand(::Type{T}, m, n) where {T<:Real} = rand(T, m, n) myrand(::Type{Complex{T}}, m, n) where {T<:Real} = rand(T, m, n) + im*rand(T, m, n) +# Wrapper so the compiler sees ws as a concrete positional argument and can elide +# the keyword NamedTuple that would otherwise allocate in Julia 1.10's kwarg machinery. +function check_allocs(Mf, ws, C, D, E, r15x5, r10x5, r5x10, r5x15) + @test @allocated(mul!(r15x5, Mf, C; cache=ws)) == 0 + @test @allocated(mul!(r10x5, Mf', D; cache=ws)) == 0 + @test @allocated(mul!(r10x5, transpose(Mf), D; cache=ws)) == 0 + @test @allocated(mul!(r5x10, D', Mf; cache=ws)) == 0 + @test @allocated(mul!(r5x10, transpose(D), Mf; cache=ws)) == 0 + @test @allocated(mul!(r15x5, Mf, E'; cache=ws)) == 0 + @test @allocated(mul!(r15x5, Mf, transpose(E); cache=ws)) == 0 + @test @allocated(mul!(r5x15, E, Mf'; cache=ws)) == 0 + @test @allocated(mul!(r5x15, E, transpose(Mf); cache=ws)) == 0 +end + @testset "FactoredMatrices" begin for T in (Float32, Float64, ComplexF32, ComplexF64) + # Mf: 15×10 (U: 15×3, V: 3×10) U = myrand(T, 15, 3) V = myrand(T, 3, 10) - Mf = FactoredMatrix(U, V, 5) + Mf = FactoredMatrix(U, V) M = Array(Mf) @test M == U*V - C = myrand(T, 10, 5) + C = myrand(T, 10, 5) # for Mf*C (15×10)*(10×5) → 15×5 + D = myrand(T, 15, 5) # for Mf'*D (10×15)*(15×5) → 10×5 + E = myrand(T, 5, 10) # for E*Mf' (5×10)*(10×15) → 5×15 @test M*C ≈ Mf*C - D = myrand(T, 15, 5) @test M'*D ≈ Mf'*D @test transpose(M)*D ≈ transpose(Mf)*D @test D'*M ≈ D'*Mf @test transpose(D)*M ≈ transpose(D)*Mf - E = myrand(T, 5, 10) @test M*adjoint(E) ≈ Mf*E' @test M*transpose(E) ≈ Mf*transpose(E) @test E*adjoint(M) ≈ E*Mf' @@ -30,10 +45,40 @@ myrand(::Type{Complex{T}}, m, n) where {T<:Real} = rand(T, m, n) + im*rand(T, m, @test !any(isnan, Mf) @test !any(isinf, Mf) + # Workspace (cache=) path: correctness + zero allocations + ws = FactoredMatrices.Workspace(Mf, 5) + r15x5 = Matrix{T}(undef, 15, 5) # Mf*C, Mf*E', Mf*transpose(E) + r10x5 = Matrix{T}(undef, 10, 5) # Mf'*D, transpose(Mf)*D + r5x10 = Matrix{T}(undef, 5, 10) # D'*Mf, transpose(D)*Mf + r5x15 = Matrix{T}(undef, 5, 15) # E*Mf', E*transpose(Mf) + + # warm up to avoid counting compilation + mul!(r15x5, Mf, C; cache=ws) + mul!(r10x5, Mf', D; cache=ws) + mul!(r10x5, transpose(Mf), D; cache=ws) + mul!(r5x10, D', Mf; cache=ws) + mul!(r5x10, transpose(D), Mf; cache=ws) + mul!(r15x5, Mf, E'; cache=ws) + mul!(r15x5, Mf, transpose(E); cache=ws) + mul!(r5x15, E, Mf'; cache=ws) + mul!(r5x15, E, transpose(Mf); cache=ws) + + mul!(r15x5, Mf, C; cache=ws); @test r15x5 ≈ M*C + mul!(r10x5, Mf', D; cache=ws); @test r10x5 ≈ M'*D + mul!(r10x5, transpose(Mf), D; cache=ws); @test r10x5 ≈ transpose(M)*D + mul!(r5x10, D', Mf; cache=ws); @test r5x10 ≈ D'*M + mul!(r5x10, transpose(D), Mf; cache=ws); @test r5x10 ≈ transpose(D)*M + mul!(r15x5, Mf, E'; cache=ws); @test r15x5 ≈ M*E' + mul!(r15x5, Mf, transpose(E); cache=ws); @test r15x5 ≈ M*transpose(E) + mul!(r5x15, E, Mf'; cache=ws); @test r5x15 ≈ E*M' + mul!(r5x15, E, transpose(Mf); cache=ws); @test r5x15 ≈ E*transpose(M) + + check_allocs(Mf, ws, C, D, E, r15x5, r10x5, r5x10, r5x15) + U1 = myrand(T, 15, 4) V1 = myrand(T, 4, 10) M1 = U1*V1 - M1f = FactoredMatrix(U1, V1, 5) + M1f = FactoredMatrix(U1, V1) @test sum(abs2, M-M1) ≈ FactoredMatrices.ssd(Mf, M1f) end end