[SparseArraysBase] Rename SparseArrayInterface to SparseArraysBase (#1591)

Author: mtfishman

.JuliaFormatter.toml

@@ -0,0 +1,2 @@
+style = "blue"
+indent = 2

README.md

@@ -0,0 +1,60 @@
+# SparseArraysBase
+
+Defines a generic interface for sparse arrays in Julia.
+
+The minimal interface is:
+```julia
+nonzeros(a::AbstractArray) = ...
+nonzero_index_to_index(a::AbstractArray, Inz) = ...
+index_to_nonzero_index(a::AbstractArray{<:Any,N}, I::CartesianIndex{N}) where {N} = ...
+Broadcast.BroadcastStyle(arraytype::Type{<:AbstractArray}) = SparseArraysBase.SparseArrayStyle{ndims(arraytype)}()
+```
+Once these are defined, along with Julia AbstractArray interface functions like
+`Base.size` and `Base.similar`, functions like the following will take advantage of sparsity:
+```julia
+SparseArraysBase.nonzero_length # SparseArrays.nnz
+SparseArraysBase.sparse_getindex
+SparseArraysBase.sparse_setindex!
+SparseArraysBase.sparse_map!
+SparseArraysBase.sparse_copy!
+SparseArraysBase.sparse_copyto!
+SparseArraysBase.sparse_permutedims!
+```
+which can be used to define the corresponding `Base` functions.
+
+## TODO
+Still need to implement `Base` functions:
+```julia
+[x] sparse_zero(a::AbstractArray) = similar(a)
+[x] sparse_iszero(a::AbstractArray) = iszero(nonzero_length(a)) # Uses `all`, make `sparse_all`?
+[x] sparse_one(a::AbstractArray) = ...
+[x] sparse_isreal(a::AbstractArray) = ... # Uses `all`, make `sparse_all`?
+[x] sparse_isequal(a1::AbstractArray, a2::AbstractArray) = ...
+[x] sparse_conj!(a::AbstractArray) = conj!(nonzeros(a))
+[x] sparse_reshape(a::AbstractArray, dims) = ...
+[ ] sparse_all(f, a::AbstractArray) = ...
+[ ] sparse_getindex(a::AbstractArray, 1:2, 2:3) = ... # Slicing
+```
+`LinearAlgebra` functions:
+```julia
+[ ] sparse_mul!
+[ ] sparse_lmul!
+[ ] sparse_ldiv!
+[ ] sparse_rdiv!
+[ ] sparse_axpby!
+[ ] sparse_axpy!
+[ ] sparse_norm
+[ ] sparse_dot/sparse_inner
+[ ] sparse_adoint!
+[ ] sparse_transpose!
+
+# Using conversion to `SparseMatrixCSC`:
+[ ] sparse_qr
+[ ] sparse_eigen
+[ ] sparse_svd
+```
+`TensorAlgebra` functions:
+```julia
+[ ] add!
+[ ] contract!
+```

src/SparseArraysBase.jl

@@ -0,0 +1,31 @@
+module SparseArraysBase
+include("sparsearrayinterface/arraylayouts.jl")
+include("sparsearrayinterface/densearray.jl")
+include("sparsearrayinterface/vectorinterface.jl")
+include("sparsearrayinterface/interface.jl")
+include("sparsearrayinterface/interface_optional.jl")
+include("sparsearrayinterface/indexing.jl")
+include("sparsearrayinterface/base.jl")
+include("sparsearrayinterface/map.jl")
+include("sparsearrayinterface/copyto.jl")
+include("sparsearrayinterface/broadcast.jl")
+include("sparsearrayinterface/conversion.jl")
+include("sparsearrayinterface/wrappers.jl")
+include("sparsearrayinterface/zero.jl")
+include("sparsearrayinterface/cat.jl")
+include("sparsearrayinterface/SparseArraysBaseLinearAlgebraExt.jl")
+include("abstractsparsearray/abstractsparsearray.jl")
+include("abstractsparsearray/abstractsparsematrix.jl")
+include("abstractsparsearray/abstractsparsevector.jl")
+include("abstractsparsearray/wrappedabstractsparsearray.jl")
+include("abstractsparsearray/arraylayouts.jl")
+include("abstractsparsearray/sparsearrayinterface.jl")
+include("abstractsparsearray/base.jl")
+include("abstractsparsearray/broadcast.jl")
+include("abstractsparsearray/map.jl")
+include("abstractsparsearray/baseinterface.jl")
+include("abstractsparsearray/convert.jl")
+include("abstractsparsearray/cat.jl")
+include("abstractsparsearray/SparseArraysBaseSparseArraysExt.jl")
+include("abstractsparsearray/SparseArraysBaseLinearAlgebraExt.jl")
+end

src/abstractsparsearray/SparseArraysBaseLinearAlgebraExt.jl

@@ -0,0 +1,15 @@
+using LinearAlgebra: LinearAlgebra
+
+LinearAlgebra.norm(a::AbstractSparseArray, p::Real=2) = sparse_norm(a, p)
+
+# a1 * a2 * α + a_dest * β
+function LinearAlgebra.mul!(
+  a_dest::AbstractMatrix,
+  a1::AbstractSparseMatrix,
+  a2::AbstractSparseMatrix,
+  α::Number=true,
+  β::Number=false,
+)
+  sparse_mul!(a_dest, a1, a2, α, β)
+  return a_dest
+end

src/abstractsparsearray/SparseArraysBaseSparseArraysExt.jl

@@ -0,0 +1,20 @@
+using Base: Forward
+using SparseArrays: SparseArrays, SparseMatrixCSC, findnz, getcolptr, nonzeros, rowvals
+using ..SparseArraysBase: stored_length
+
+# Julia Base `AbstractSparseArray` interface
+SparseArrays.nnz(a::AbstractSparseArray) = stored_length(a)
+
+sparse_storage(a::SparseMatrixCSC) = nonzeros(a)
+function storage_index_to_index(a::SparseMatrixCSC, I)
+  I1s, I2s = findnz(a)
+  return CartesianIndex(I1s[I], I2s[I])
+end
+function index_to_storage_index(a::SparseMatrixCSC, I::CartesianIndex{2})
+  i0, i1 = Tuple(I)
+  r1 = getcolptr(a)[i1]
+  r2 = getcolptr(a)[i1 + 1] - 1
+  (r1 > r2) && return nothing
+  r1 = searchsortedfirst(rowvals(a), i0, r1, r2, Forward)
+  return ((r1 > r2) || (rowvals(a)[r1] != i0)) ? nothing : r1
+end

src/abstractsparsearray/abstractsparsearray.jl

@@ -0,0 +1,3 @@
+using ArrayLayouts: LayoutArray
+
+abstract type AbstractSparseArray{T,N} <: LayoutArray{T,N} end

src/abstractsparsearray/abstractsparsematrix.jl

@@ -0,0 +1 @@
+const AbstractSparseMatrix{T} = AbstractSparseArray{T,2}

src/abstractsparsearray/abstractsparsevector.jl

@@ -0,0 +1 @@
+const AbstractSparseVector{T} = AbstractSparseArray{T,1}

src/abstractsparsearray/arraylayouts.jl

@@ -0,0 +1,41 @@
+using ArrayLayouts: ArrayLayouts, Dot, DualLayout, MatMulMatAdd, MatMulVecAdd, MulAdd
+using LinearAlgebra: Adjoint, Transpose
+using ..TypeParameterAccessors: parenttype
+
+function ArrayLayouts.MemoryLayout(arraytype::Type{<:AnyAbstractSparseArray})
+  return SparseLayout()
+end
+
+# TODO: Generalize to `SparseVectorLike`/`AnySparseVector`.
+function ArrayLayouts.MemoryLayout(arraytype::Type{<:Adjoint{<:Any,<:AbstractSparseVector}})
+  return DualLayout{typeof(MemoryLayout(parenttype(arraytype)))}()
+end
+# TODO: Generalize to `SparseVectorLike`/`AnySparseVector`.
+function ArrayLayouts.MemoryLayout(
+  arraytype::Type{<:Transpose{<:Any,<:AbstractSparseVector}}
+)
+  return DualLayout{typeof(MemoryLayout(parenttype(arraytype)))}()
+end
+
+function sparse_matmul!(m::MulAdd)
+  α, a1, a2, β, a_dest = m.α, m.A, m.B, m.β, m.C
+  sparse_mul!(a_dest, a1, a2, α, β)
+  return a_dest
+end
+
+function ArrayLayouts.materialize!(
+  m::MatMulMatAdd{<:AbstractSparseLayout,<:AbstractSparseLayout,<:AbstractSparseLayout}
+)
+  sparse_matmul!(m)
+  return m.C
+end
+function ArrayLayouts.materialize!(
+  m::MatMulVecAdd{<:AbstractSparseLayout,<:AbstractSparseLayout,<:AbstractSparseLayout}
+)
+  sparse_matmul!(m)
+  return m.C
+end
+
+function Base.copy(d::Dot{<:SparseLayout,<:SparseLayout})
+  return sparse_dot(d.A, d.B)
+end

src/abstractsparsearray/base.jl

@@ -0,0 +1,18 @@
+using ..SparseArraysBase: SparseArraysBase
+
+# Base
+function Base.:(==)(a1::AnyAbstractSparseArray, a2::AnyAbstractSparseArray)
+  return SparseArraysBase.sparse_isequal(a1, a2)
+end
+
+function Base.reshape(a::AnyAbstractSparseArray, dims::Tuple{Vararg{Int}})
+  return SparseArraysBase.sparse_reshape(a, dims)
+end
+
+function Base.zero(a::AnyAbstractSparseArray)
+  return SparseArraysBase.sparse_zero(a)
+end
+
+function Base.one(a::AnyAbstractSparseArray)
+  return SparseArraysBase.sparse_one(a)
+end