AbstractSparseArray{Tv,Ti,N}

Supertype forN-dimensional sparse arrays (or array-like types) with elements of typeTv and index typeTi.SparseMatrixCSC,SparseVector andSuiteSparse.CHOLMOD.Sparse are subtypes of this.

AbstractSparseVector{Tv,Ti}

Supertype for one-dimensional sparse arrays (or array-like types) with elements of typeTv and index typeTi. Alias forAbstractSparseArray{Tv,Ti,1}.

AbstractSparseMatrix{Tv,Ti}

Supertype for two-dimensional sparse arrays (or array-like types) with elements of typeTv and index typeTi. Alias forAbstractSparseArray{Tv,Ti,2}.

SparseVector{Tv,Ti<:Integer} <: AbstractSparseVector{Tv,Ti}

Vector type for storing sparse vectors. Can be created by passing the length of the vector, asorted vector of non-zero indices, and a vector of non-zero values.

For instance, the vector[5, 6, 0, 7] can be represented as

SparseVector(4, [1, 2, 4], [5, 6, 7])

This indicates that the element at index 1 is 5, at index 2 is 6, at index 3 iszero(Int), and at index 4 is 7.

It may be more convenient to create sparse vectors directly from dense vectors usingsparse as

sparse([5, 6, 0, 7])

yields the same sparse vector.

SparseMatrixCSC{Tv,Ti<:Integer} <: AbstractSparseMatrixCSC{Tv,Ti}

Matrix type for storing sparse matrices in theCompressed Sparse Column format. The standard way of constructing SparseMatrixCSC is through thesparse function. See alsospzeros,spdiagm andsprand.

sparse(A::Union{AbstractVector, AbstractMatrix})

Convert a vector or matrixA into a sparse array. Numerical zeros inA are turned into structural zeros.

Examples

julia> A = Matrix(1.0I, 3, 3)3×3 Matrix{Float64}: 1.0  0.0  0.0 0.0  1.0  0.0 0.0  0.0  1.0julia> sparse(A)3×3 SparseMatrixCSC{Float64, Int64} with 3 stored entries: 1.0   ⋅    ⋅  ⋅   1.0   ⋅  ⋅    ⋅   1.0julia> [1.0, 0.0, 1.0]3-element Vector{Float64}: 1.0 0.0 1.0julia> sparse([1.0, 0.0, 1.0])3-element SparseVector{Float64, Int64} with 2 stored entries:  [1]  =  1.0  [3]  =  1.0

sparse(I, J, V,[ m, n, combine])

Create a sparse matrixS of dimensionsm x n such thatS[I[k], J[k]] = V[k]. Thecombine function is used to combine duplicates. Ifm andn are not specified, they are set tomaximum(I) andmaximum(J) respectively. If thecombine function is not supplied,combine defaults to+ unless the elements ofV are Booleans in which casecombine defaults to|. All elements ofI must satisfy1 <= I[k] <= m, and all elements ofJ must satisfy1 <= J[k] <= n. Numerical zeros in (I,J,V) are retained as structural nonzeros; to drop numerical zeros, usedropzeros!.

For additional documentation and an expert driver, seeSparseArrays.sparse!.

Examples

julia> Is = [1; 2; 3];julia> Js = [1; 2; 3];julia> Vs = [1; 2; 3];julia> sparse(Is, Js, Vs)3×3 SparseMatrixCSC{Int64, Int64} with 3 stored entries: 1  ⋅  ⋅ ⋅  2  ⋅ ⋅  ⋅  3

sparse!(I::AbstractVector{Ti}, J::AbstractVector{Ti}, V::AbstractVector{Tv},        m::Integer, n::Integer, combine, klasttouch::Vector{Ti},        csrrowptr::Vector{Ti}, csrcolval::Vector{Ti}, csrnzval::Vector{Tv},        [csccolptr::Vector{Ti}], [cscrowval::Vector{Ti}, cscnzval::Vector{Tv}] ) where {Tv,Ti<:Integer}

Parent of and expert driver forsparse; seesparse for basic usage. This method allows the user to provide preallocated storage forsparse's intermediate objects and result as described below. This capability enables more efficient successive construction ofSparseMatrixCSCs from coordinate representations, and also enables extraction of an unsorted-column representation of the result's transpose at no additional cost.

This method consists of three major steps: (1) Counting-sort the provided coordinate representation into an unsorted-row CSR form including repeated entries. (2) Sweep through the CSR form, simultaneously calculating the desired CSC form's column-pointer array, detecting repeated entries, and repacking the CSR form with repeated entries combined; this stage yields an unsorted-row CSR form with no repeated entries. (3) Counting-sort the preceding CSR form into a fully-sorted CSC form with no repeated entries.

Input arrayscsrrowptr,csrcolval, andcsrnzval constitute storage for the intermediate CSR forms and requirelength(csrrowptr) >= m + 1,length(csrcolval) >= length(I), andlength(csrnzval >= length(I)). Input arrayklasttouch, workspace for the second stage, requireslength(klasttouch) >= n. Optional input arrayscsccolptr,cscrowval, andcscnzval constitute storage for the returned CSC formS. If necessary, these are resized automatically to satisfylength(csccolptr) = n + 1,length(cscrowval) = nnz(S) andlength(cscnzval) = nnz(S); hence, ifnnz(S) is unknown at the outset, passing in empty vectors of the appropriate type (Vector{Ti}() andVector{Tv}() respectively) suffices, or calling thesparse! method neglectingcscrowval andcscnzval.

On return,csrrowptr,csrcolval, andcsrnzval contain an unsorted-column representation of the result's transpose.

You may reuse the input arrays' storage (I,J,V) for the output arrays (csccolptr,cscrowval,cscnzval). For example, you may callsparse!(I, J, V, csrrowptr, csrcolval, csrnzval, I, J, V). Note that they will be resized to satisfy the conditions above.

For the sake of efficiency, this method performs no argument checking beyond1 <= I[k] <= m and1 <= J[k] <= n. Use with care. Testing with--check-bounds=yes is wise.

This method runs inO(m, n, length(I)) time. The HALFPERM algorithm described in F. Gustavson, "Two fast algorithms for sparse matrices: multiplication and permuted transposition," ACM TOMS 4(3), 250-269 (1978) inspired this method's use of a pair of counting sorts.

SparseArrays.sparse!(I, J, V, [m, n, combine]) -> SparseMatrixCSC

Variant ofsparse! that re-uses the input vectors (I,J,V) for the final matrix storage. After construction the input vectors will alias the matrix buffers;S.colptr === I,S.rowval === J, andS.nzval === V holds, and they will beresize!d as necessary.

Note that some work buffers will still be allocated. Specifically, this method is a convenience wrapper aroundsparse!(I, J, V, m, n, combine, klasttouch, csrrowptr, csrcolval, csrnzval, csccolptr, cscrowval, cscnzval) where this method allocatesklasttouch,csrrowptr,csrcolval, andcsrnzval of appropriate size, but reusesI,J, andV forcsccolptr,cscrowval, andcscnzval.

Argumentsm,n, andcombine defaults tomaximum(I),maximum(J), and+, respectively.

sparsevec(I, V, [m, combine])

Create a sparse vectorS of lengthm such thatS[I[k]] = V[k]. Duplicates are combined using thecombine function, which defaults to+ if nocombine argument is provided, unless the elements ofV are Booleans in which casecombine defaults to|.

Examples

julia> II = [1, 3, 3, 5]; V = [0.1, 0.2, 0.3, 0.2];julia> sparsevec(II, V)5-element SparseVector{Float64, Int64} with 3 stored entries:  [1]  =  0.1  [3]  =  0.5  [5]  =  0.2julia> sparsevec(II, V, 8, -)8-element SparseVector{Float64, Int64} with 3 stored entries:  [1]  =  0.1  [3]  =  -0.1  [5]  =  0.2julia> sparsevec([1, 3, 1, 2, 2], [true, true, false, false, false])3-element SparseVector{Bool, Int64} with 3 stored entries:  [1]  =  1  [2]  =  0  [3]  =  1

sparsevec(d::Dict, [m])

Create a sparse vector of lengthm where the nonzero indices are keys from the dictionary, and the nonzero values are the values from the dictionary.

Examples

julia> sparsevec(Dict(1 => 3, 2 => 2))2-element SparseVector{Int64, Int64} with 2 stored entries:  [1]  =  3  [2]  =  2

sparsevec(A)

Convert a vectorA into a sparse vector of lengthm. Numerical zeros inA are turned into structural zeros.

Examples

julia> sparsevec([1.0, 2.0, 0.0, 0.0, 3.0, 0.0])6-element SparseVector{Float64, Int64} with 3 stored entries:  [1]  =  1.0  [2]  =  2.0  [5]  =  3.0

similar(A::AbstractSparseMatrixCSC{Tv,Ti}, [::Type{TvNew}, ::Type{TiNew}, m::Integer, n::Integer]) where {Tv,Ti}

Create an uninitialized mutable array with the given element type, index type, and size, based upon the given sourceSparseMatrixCSC. The new sparse matrix maintains the structure of the original sparse matrix, except in the case where dimensions of the output matrix are different from the output.

The output matrix has zeros in the same locations as the input, but uninitialized values for the nonzero locations.

issparse(S)

Returnstrue ifS is sparse, andfalse otherwise.

Examples

julia> sv = sparsevec([1, 4], [2.3, 2.2], 10)10-element SparseVector{Float64, Int64} with 2 stored entries:  [1]  =  2.3  [4]  =  2.2julia> issparse(sv)truejulia> issparse(Array(sv))false

nnz(A)

Returns the number of stored (filled) elements in a sparse array.

Examples

julia> A = sparse(2I, 3, 3)3×3 SparseMatrixCSC{Int64, Int64} with 3 stored entries: 2  ⋅  ⋅ ⋅  2  ⋅ ⋅  ⋅  2julia> nnz(A)3

findnz(A::SparseMatrixCSC)

Return a tuple(I, J, V) whereI andJ are the row and column indices of the stored ("structurally non-zero") values in sparse matrixA, andV is a vector of the values.

Examples

julia> A = sparse([1 2 0; 0 0 3; 0 4 0])3×3 SparseMatrixCSC{Int64, Int64} with 4 stored entries: 1  2  ⋅ ⋅  ⋅  3 ⋅  4  ⋅julia> findnz(A)([1, 1, 3, 2], [1, 2, 2, 3], [1, 2, 4, 3])

spzeros([type,]m[,n])

Create a sparse vector of lengthm or sparse matrix of sizem x n. This sparse array will not contain any nonzero values. No storage will be allocated for nonzero values during construction. The type defaults toFloat64 if not specified.

Examples

julia> spzeros(3, 3)3×3 SparseMatrixCSC{Float64, Int64} with 0 stored entries:  ⋅    ⋅    ⋅  ⋅    ⋅    ⋅  ⋅    ⋅    ⋅julia> spzeros(Float32, 4)4-element SparseVector{Float32, Int64} with 0 stored entries

spzeros([type], I::AbstractVector, J::AbstractVector, [m, n])

Create a sparse matrixS of dimensionsm x n with structural zeros atS[I[k], J[k]].

This method can be used to construct the sparsity pattern of the matrix, and is more efficient than using e.g.sparse(I, J, zeros(length(I))).

For additional documentation and an expert driver, seeSparseArrays.spzeros!.

spzeros!(::Type{Tv}, I::AbstractVector{Ti}, J::AbstractVector{Ti}, m::Integer, n::Integer,         klasttouch::Vector{Ti}, csrrowptr::Vector{Ti}, csrcolval::Vector{Ti},         [csccolptr::Vector{Ti}], [cscrowval::Vector{Ti}, cscnzval::Vector{Tv}]) where {Tv,Ti<:Integer}

Parent of and expert driver forspzeros(I, J) allowing user to provide preallocated storage for intermediate objects. This method is tospzeros whatSparseArrays.sparse! is tosparse. See documentation forSparseArrays.sparse! for details and required buffer lengths.

SparseArrays.spzeros!(::Type{Tv}, I, J, [m, n]) -> SparseMatrixCSC{Tv}

Variant ofspzeros! that re-uses the input vectorsI andJ for the final matrix storage. After construction the input vectors will alias the matrix buffers;S.colptr === I andS.rowval === J holds, and they will beresize!d as necessary.

Note that some work buffers will still be allocated. Specifically, this method is a convenience wrapper aroundspzeros!(Tv, I, J, m, n, klasttouch, csrrowptr, csrcolval, csccolptr, cscrowval) where this method allocatesklasttouch,csrrowptr, andcsrcolval of appropriate size, but reusesI andJ forcsccolptr andcscrowval.

Argumentsm andn defaults tomaximum(I) andmaximum(J).

spdiagm(kv::Pair{<:Integer,<:AbstractVector}...)spdiagm(m::Integer, n::Integer, kv::Pair{<:Integer,<:AbstractVector}...)

Construct a sparse diagonal matrix fromPairs of vectors and diagonals. Each vectorkv.second will be placed on thekv.first diagonal. By default, the matrix is square and its size is inferred fromkv, but a non-square sizem×n (padded with zeros as needed) can be specified by passingm,n as the first arguments.

Examples

julia> spdiagm(-1 => [1,2,3,4], 1 => [4,3,2,1])5×5 SparseMatrixCSC{Int64, Int64} with 8 stored entries: ⋅  4  ⋅  ⋅  ⋅ 1  ⋅  3  ⋅  ⋅ ⋅  2  ⋅  2  ⋅ ⋅  ⋅  3  ⋅  1 ⋅  ⋅  ⋅  4  ⋅

spdiagm(v::AbstractVector)spdiagm(m::Integer, n::Integer, v::AbstractVector)

Construct a sparse matrix with elements of the vector as diagonal elements. By default (no givenm andn), the matrix is square and its size is given bylength(v), but a non-square sizem×n can be specified by passingm andn as the first arguments.

Examples

julia> spdiagm([1,2,3])3×3 SparseMatrixCSC{Int64, Int64} with 3 stored entries: 1  ⋅  ⋅ ⋅  2  ⋅ ⋅  ⋅  3julia> spdiagm(sparse([1,0,3]))3×3 SparseMatrixCSC{Int64, Int64} with 2 stored entries: 1  ⋅  ⋅ ⋅  ⋅  ⋅ ⋅  ⋅  3

sparse_hcat(A...)

Concatenate along dimension 2. Return a SparseMatrixCSC object.

sparse_vcat(A...)

Concatenate along dimension 1. Return a SparseMatrixCSC object.

sparse_hvcat(rows::Tuple{Vararg{Int}}, values...)

Sparse horizontal and vertical concatenation in one call. This function is called for block matrix syntax. The first argument specifies the number of arguments to concatenate in each block row.

blockdiag(A...)

Concatenate matrices block-diagonally. Currently only implemented for sparse matrices.

Examples

julia> blockdiag(sparse(2I, 3, 3), sparse(4I, 2, 2))5×5 SparseMatrixCSC{Int64, Int64} with 5 stored entries: 2  ⋅  ⋅  ⋅  ⋅ ⋅  2  ⋅  ⋅  ⋅ ⋅  ⋅  2  ⋅  ⋅ ⋅  ⋅  ⋅  4  ⋅ ⋅  ⋅  ⋅  ⋅  4

sprand([rng],[T::Type],m,[n],p::AbstractFloat)sprand([rng],m,[n],p::AbstractFloat,[rfn=rand])

Create a random lengthm sparse vector orm byn sparse matrix, in which the probability of any element being nonzero is independently given byp (and hence the mean density of nonzeros is also exactlyp). The optionalrng argument specifies a random number generator, seeRandom Numbers. The optionalT argument specifies the element type, which defaults toFloat64.

By default, nonzero values are sampled from a uniform distribution using therand function, i.e. byrand(T), orrand(rng, T) ifrng is supplied; for the defaultT=Float64, this corresponds to nonzero values sampled uniformly in[0,1).

You can sample nonzero values from a different distribution by passing a customrfn function instead ofrand. This should be a functionrfn(k) that returns an array ofk random numbers sampled from the desired distribution; alternatively, ifrng is supplied, it should instead be a functionrfn(rng, k).

Examples

julia> sprand(Bool, 2, 2, 0.5)2×2 SparseMatrixCSC{Bool, Int64} with 2 stored entries: 1  1 ⋅  ⋅julia> sprand(Float64, 3, 0.75)3-element SparseVector{Float64, Int64} with 2 stored entries:  [1]  =  0.795547  [2]  =  0.49425

sprandn([rng][,Type],m[,n],p::AbstractFloat)

Create a random sparse vector of lengthm or sparse matrix of sizem byn with the specified (independent) probabilityp of any entry being nonzero, where nonzero values are sampled from the normal distribution. The optionalrng argument specifies a random number generator, seeRandom Numbers.

Examples

julia> sprandn(2, 2, 0.75)2×2 SparseMatrixCSC{Float64, Int64} with 3 stored entries: -1.20577     ⋅  0.311817  -0.234641

nonzeros(A)

Return a vector of the structural nonzero values in sparse arrayA. This includes zeros that are explicitly stored in the sparse array. The returned vector points directly to the internal nonzero storage ofA, and any modifications to the returned vector will mutateA as well. Seerowvals andnzrange.

Examples

julia> A = sparse(2I, 3, 3)3×3 SparseMatrixCSC{Int64, Int64} with 3 stored entries: 2  ⋅  ⋅ ⋅  2  ⋅ ⋅  ⋅  2julia> nonzeros(A)3-element Vector{Int64}: 2 2 2

rowvals(A)

Return a vector of the row indices of sparse arrayA. Any modifications to the returned vector will mutateA as well. Providing access to how the row indices are stored internally can be useful in conjunction with iterating over structural nonzero values. See alsononzeros andnzrange.

Examples

julia> A = sparse(2I, 3, 3)3×3 SparseMatrixCSC{Int64, Int64} with 3 stored entries: 2  ⋅  ⋅ ⋅  2  ⋅ ⋅  ⋅  2julia> rowvals(A)3-element Vector{Int64}: 1 2 3

nzrange(A, col::Integer)

Return the range of indices to the structural nonzero values of columncol of sparse arrayA. In conjunction withnonzeros androwvals, this allows for convenient iterating over a sparse matrix :

A = sparse(I,J,V)rows = rowvals(A)vals = nonzeros(A)m, n = size(A)for j = 1:n   for i in nzrange(A, j)      row = rows[i]      val = vals[i]      # perform sparse wizardry...   endend

nzrange(x::SparseVectorUnion, col)

Give the range of indices to the structural nonzero values of a sparse vector. The column indexcol is ignored (assumed to be1).

droptol!(A::AbstractSparseMatrixCSC, tol)

Removes stored values fromA whose absolute value is less than or equal totol.

droptol!(x::AbstractCompressedVector, tol)

Removes stored values fromx whose absolute value is less than or equal totol.

dropzeros!(x::AbstractCompressedVector)

Removes stored numerical zeros fromx.

For an out-of-place version, seedropzeros. For algorithmic information, seefkeep!.

dropzeros(A::AbstractSparseMatrixCSC;)

Generates a copy ofA and removes stored numerical zeros from that copy.

For an in-place version and algorithmic information, seedropzeros!.

Examples

julia> A = sparse([1, 2, 3], [1, 2, 3], [1.0, 0.0, 1.0])3×3 SparseMatrixCSC{Float64, Int64} with 3 stored entries: 1.0   ⋅    ⋅  ⋅   0.0   ⋅  ⋅    ⋅   1.0julia> dropzeros(A)3×3 SparseMatrixCSC{Float64, Int64} with 2 stored entries: 1.0   ⋅    ⋅  ⋅    ⋅    ⋅  ⋅    ⋅   1.0

dropzeros(x::AbstractCompressedVector)

Generates a copy ofx and removes numerical zeros from that copy.

For an in-place version and algorithmic information, seedropzeros!.

Examples

julia> A = sparsevec([1, 2, 3], [1.0, 0.0, 1.0])3-element SparseVector{Float64, Int64} with 3 stored entries:  [1]  =  1.0  [2]  =  0.0  [3]  =  1.0julia> dropzeros(A)3-element SparseVector{Float64, Int64} with 2 stored entries:  [1]  =  1.0  [3]  =  1.0

permute(A::AbstractSparseMatrixCSC{Tv,Ti}, p::AbstractVector{<:Integer},        q::AbstractVector{<:Integer}) where {Tv,Ti}

Bilaterally permuteA, returningPAQ (A[p,q]). Column-permutationq's length must matchA's column count (length(q) == size(A, 2)). Row-permutationp's length must matchA's row count (length(p) == size(A, 1)).

For expert drivers and additional information, seepermute!.

Examples

julia> A = spdiagm(0 => [1, 2, 3, 4], 1 => [5, 6, 7])4×4 SparseMatrixCSC{Int64, Int64} with 7 stored entries: 1  5  ⋅  ⋅ ⋅  2  6  ⋅ ⋅  ⋅  3  7 ⋅  ⋅  ⋅  4julia> permute(A, [4, 3, 2, 1], [1, 2, 3, 4])4×4 SparseMatrixCSC{Int64, Int64} with 7 stored entries: ⋅  ⋅  ⋅  4 ⋅  ⋅  3  7 ⋅  2  6  ⋅ 1  5  ⋅  ⋅julia> permute(A, [1, 2, 3, 4], [4, 3, 2, 1])4×4 SparseMatrixCSC{Int64, Int64} with 7 stored entries: ⋅  ⋅  5  1 ⋅  6  2  ⋅ 7  3  ⋅  ⋅ 4  ⋅  ⋅  ⋅

permute!(X::AbstractSparseMatrixCSC{Tv,Ti}, A::AbstractSparseMatrixCSC{Tv,Ti},         p::AbstractVector{<:Integer}, q::AbstractVector{<:Integer},         [C::AbstractSparseMatrixCSC{Tv,Ti}]) where {Tv,Ti}

Bilaterally permuteA, storing resultPAQ (A[p,q]) inX. Stores intermediate result(AQ)^T (transpose(A[:,q])) in optional argumentC if present. Requires that none ofX,A, and, if present,C alias each other; to store resultPAQ back intoA, use the following method lackingX:

permute!(A::AbstractSparseMatrixCSC{Tv,Ti}, p::AbstractVector{<:Integer},         q::AbstractVector{<:Integer}[, C::AbstractSparseMatrixCSC{Tv,Ti},         [workcolptr::Vector{Ti}]]) where {Tv,Ti}

X's dimensions must match those ofA (size(X, 1) == size(A, 1) andsize(X, 2) == size(A, 2)), andX must have enough storage to accommodate all allocated entries inA (length(rowvals(X)) >= nnz(A) andlength(nonzeros(X)) >= nnz(A)). Column-permutationq's length must matchA's column count (length(q) == size(A, 2)). Row-permutationp's length must matchA's row count (length(p) == size(A, 1)).

C's dimensions must match those oftranspose(A) (size(C, 1) == size(A, 2) andsize(C, 2) == size(A, 1)), andC must have enough storage to accommodate all allocated entries inA (length(rowvals(C)) >= nnz(A) andlength(nonzeros(C)) >= nnz(A)).

For additional (algorithmic) information, and for versions of these methods that forgo argument checking, see (unexported) parent methodsunchecked_noalias_permute! andunchecked_aliasing_permute!.

See alsopermute.

halfperm!(X::AbstractSparseMatrixCSC{Tv,Ti}, A::AbstractSparseMatrixCSC{TvA,Ti},          q::AbstractVector{<:Integer}, f::Function = identity) where {Tv,TvA,Ti}

Column-permute and transposeA, simultaneously applyingf to each entry ofA, storing the result(f(A)Q)^T (map(f, transpose(A[:,q]))) inX.

Element typeTv ofX must matchf(::TvA), whereTvA is the element type ofA.X's dimensions must match those oftranspose(A) (size(X, 1) == size(A, 2) andsize(X, 2) == size(A, 1)), andX must have enough storage to accommodate all allocated entries inA (length(rowvals(X)) >= nnz(A) andlength(nonzeros(X)) >= nnz(A)). Column-permutationq's length must matchA's column count (length(q) == size(A, 2)).

This method is the parent of several methods performing transposition and permutation operations onSparseMatrixCSCs. As this method performs no argument checking, prefer the safer child methods ([c]transpose[!],permute[!]) to direct use.

This method implements theHALFPERM algorithm described in F. Gustavson, "Two fast algorithms for sparse matrices: multiplication and permuted transposition," ACM TOMS 4(3), 250-269 (1978). The algorithm runs inO(size(A, 1), size(A, 2), nnz(A)) time and requires no space beyond that passed in.

ftranspose!(X::AbstractSparseMatrixCSC{Tv,Ti}, A::AbstractSparseMatrixCSC{Tv,Ti}, f::Function) where {Tv,Ti}

TransposeA and store it inX while applying the functionf to the non-zero elements. Does not remove the zeros created byf.size(X) must be equal tosize(transpose(A)). No additional memory is allocated other than resizing the rowval and nzval ofX, if needed.

Seehalfperm!