Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion Project.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name = "FactoredMatrices"
uuid = "13d07ad6-c0d4-11e8-35b1-91a532e61cc8"
authors = ["Tim Holy <tim.holy@gmail.com>"]
version = "0.1.2"
version = "0.1.3"

[deps]
LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
Expand Down
236 changes: 175 additions & 61 deletions src/FactoredMatrices.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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

"""
Expand Down
55 changes: 50 additions & 5 deletions test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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
Loading