Export AbstractSparseMatrixCSC + interface

docs/src/index.md

@@ -231,6 +231,7 @@ DocTestSetup = nothing
 SparseArrays.AbstractSparseArray
 SparseArrays.AbstractSparseVector
 SparseArrays.AbstractSparseMatrix
+SparseArrays.AbstractSparseMatrixCSC
 SparseArrays.SparseVector
 SparseArrays.SparseMatrixCSC
 SparseArrays.sparse
@@ -252,6 +253,7 @@ SparseArrays.sprandn
 SparseArrays.nonzeros
 SparseArrays.rowvals
 SparseArrays.nzrange
+SparseArrays.getcolptr
 SparseArrays.droptol!
 SparseArrays.dropzeros!
 SparseArrays.dropzeros

src/SparseArrays.jl

@@ -29,8 +29,8 @@ import Base: adjoint, argmin, argmax, Array, broadcast, circshift!, complex, Com
 using Random: default_rng, AbstractRNG, randsubseq, randsubseq!
 
 export AbstractSparseArray, AbstractSparseMatrix, AbstractSparseVector,
-    SparseMatrixCSC, SparseVector, blockdiag, droptol!, dropzeros!, dropzeros,
-    issparse, nonzeros, nzrange, rowvals, sparse, sparsevec, spdiagm,
+    AbstractSparseMatrixCSC, SparseMatrixCSC, SparseVector, blockdiag, droptol!, dropzeros!, dropzeros,
+    issparse, nonzeros, nzrange, rowvals, getcolptr, sparse, sparsevec, spdiagm,
     sprand, sprandn, spzeros, nnz, permute, findnz,  fkeep!, ftranspose!,
     sparse_hcat, sparse_vcat, sparse_hvcat
 

src/abstractsparse.jl

@@ -38,6 +38,8 @@ const AbstractSparseVecOrMat = Union{AbstractSparseVector,AbstractSparseMatrix}
     AbstractSparseMatrixCSC{Tv,Ti<:Integer} <: AbstractSparseMatrix{Tv,Ti}
 
 Supertype for matrix with compressed sparse column (CSC).
+Subtypes of this type are expected to follow the `AbstractSparseMatrixCSC` interface
+consisting of  [`nnz`](@ref),  [`rowvals`](@ref),  [`nzrange`](@ref), [`nonzeros`](@ref) and [`getcolptr`](@ref).
 """
 abstract type AbstractSparseMatrixCSC{Tv,Ti<:Integer} <: AbstractSparseMatrix{Tv,Ti} end
 

src/sparsematrix.jl

@@ -191,6 +191,30 @@
         Tuple{Base.Slice{Base.OneTo{Int}},I}} where {I<:AbstractVector{<:Integer}}
 const SparseMatrixCSCUnion2{Tv,Ti} = Union{AbstractSparseMatrixCSC{Tv,Ti}, SparseMatrixCSCColumnSubset{Tv,Ti}}
 
+"""
+    getcolptr(A::AbstractSparseMatrixCSC)
+
+Return a vector of column pointers of `A`. Any modifications to the returned
+vector will mutate `A` as well. Providing access to how the column pointers are
+stored internally can be useful in conjunction with  passing data to factorizations
+and preconditioners. See also [`rowvals`](@ref), [`nonzeros`](@ref) and [`nzrange`](@ref).
+
+# Examples
+```jldoctest
+julia> A = sparse(2I, 3, 3)
+3×3 SparseMatrixCSC{Int64, Int64} with 3 stored entries:
+ 2  ⋅  ⋅
+ ⋅  2  ⋅
+ ⋅  ⋅  2
+
+julia> getcolptr(A)
+4-element Vector{Int64}:
+ 1
+ 2
+ 3
+ 4
+```
+"""
 getcolptr(S::SorF)     = getfield(S, :colptr)
 getcolptr(S::SparseMatrixCSCView) = view(getcolptr(parent(S)), first(S.indices[2]):(last(S.indices[2]) + 1))
 getcolptr(S::SparseMatrixCSCColumnSubset) = error("getcolptr not well-defined for $(typeof(S))")
@@ -236,7 +260,7 @@
 includes zeros that are explicitly stored in the sparse array. The returned
 vector points directly to the internal nonzero storage of `A`, and any
 modifications to the returned vector will mutate `A` as well. See
-[`rowvals`](@ref) and [`nzrange`](@ref).
+[`rowvals`](@ref), [`getcolptr`](@ref) and [`nzrange`](@ref).
 
 # Examples
 ```jldoctest
@@ -264,7 +288,7 @@
 Return a vector of the row indices of `A`. Any modifications to the returned
 vector will mutate `A` as well. Providing access to how the row indices are
 stored internally can be useful in conjunction with iterating over structural
-nonzero values. See also [`nonzeros`](@ref) and [`nzrange`](@ref).
+nonzero values. See also [`getcolptr`](@ref), [`nonzeros`](@ref) and [`nzrange`](@ref).
 
 # Examples
 ```jldoctest
@@ -744,11 +768,13 @@
 end
 
 # converting between SparseMatrixCSC types
-SparseMatrixCSC(S::AbstractSparseMatrixCSC) = copy(S)
+
 AbstractMatrix{Tv}(A::AbstractSparseMatrixCSC) where {Tv} = SparseMatrixCSC{Tv}(A)
-SparseMatrixCSC{Tv}(S::AbstractSparseMatrixCSC{Tv}) where {Tv} = copy(S)
+SparseMatrixCSC{Tv}(S::AbstractSparseMatrixCSC) where {Tv} = SparseMatrixCSC{Tv}(S)
 SparseMatrixCSC{Tv}(S::AbstractSparseMatrixCSC) where {Tv} = SparseMatrixCSC{Tv,eltype(getcolptr(S))}(S)
-SparseMatrixCSC{Tv,Ti}(S::AbstractSparseMatrixCSC{Tv,Ti}) where {Tv,Ti} = copy(S)
+SparseMatrixCSC(S::SparseMatrixCSC)=copy(S)
+
+
 function SparseMatrixCSC{Tv,Ti}(S::AbstractSparseMatrixCSC) where {Tv,Ti}
     eltypeTicolptr = Vector{Ti}(getcolptr(S))
     eltypeTirowval = Vector{Ti}(rowvals(S))