Sparse Arrays

Julia has support for sparse vectors and sparse matrices in the SparseArrays stdlib module. Sparse arrays are arrays that contain enough zeros that storing them in a special data structure leads to savings in space and execution time, compared to dense arrays.

External packages which implement different sparse storage types, multidimensional sparse arrays, and more can be found in Noteworthy External Sparse Packages

Compressed Sparse Column (CSC) Sparse Matrix Storage

In Julia, sparse matrices are stored in the Compressed Sparse Column (CSC) format. Julia sparse matrices have the type SparseMatrixCSC{Tv,Ti}, where Tv is the type of the stored values, and Ti is the integer type for storing column pointers and row indices. The internal representation of SparseMatrixCSC is as follows:

struct SparseMatrixCSC{Tv,Ti<:Integer} <: AbstractSparseMatrixCSC{Tv,Ti}
    m::Int                  # Number of rows
    n::Int                  # Number of columns
    colptr::Vector{Ti}      # Column j is in colptr[j]:(colptr[j+1]-1)
    rowval::Vector{Ti}      # Row indices of stored values
    nzval::Vector{Tv}       # Stored values, typically nonzeros
end

The compressed sparse column storage makes it easy and quick to access the elements in the column of a sparse matrix, whereas accessing the sparse matrix by rows is considerably slower. Operations such as insertion of previously unstored entries one at a time in the CSC structure tend to be slow. This is because all elements of the sparse matrix that are beyond the point of insertion have to be moved one place over.

All operations on sparse matrices are carefully implemented to exploit the CSC data structure for performance, and to avoid expensive operations.

If you have data in CSC format from a different application or library, and wish to import it in Julia, make sure that you use 1-based indexing. The row indices in every column need to be sorted, and if they are not, the matrix will display incorrectly. If your SparseMatrixCSC object contains unsorted row indices, one quick way to sort them is by doing a double transpose. Since the transpose operation is lazy, make a copy to materialize each transpose.

In some applications, it is convenient to store explicit zero values in a SparseMatrixCSC. These are accepted by functions in Base (but there is no guarantee that they will be preserved in mutating operations). Such explicitly stored zeros are treated as structural nonzeros by many routines. The nnz function returns the number of elements explicitly stored in the sparse data structure, including non-structural zeros. In order to count the exact number of numerical nonzeros, use count(!iszero, x), which inspects every stored element of a sparse matrix. dropzeros, and the in-place dropzeros!, can be used to remove stored zeros from the sparse matrix.

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

julia> dropzeros(A)
3×3 SparseMatrixCSC{Int64, Int64} with 2 stored entries:
 ⋅  ⋅  1
 ⋅  2  ⋅
 ⋅  ⋅  ⋅

Sparse Vector Storage

Sparse vectors are stored in a close analog to compressed sparse column format for sparse matrices. In Julia, sparse vectors have the type SparseVector{Tv,Ti} where Tv is the type of the stored values and Ti the integer type for the indices. The internal representation is as follows:

struct SparseVector{Tv,Ti<:Integer} <: AbstractSparseVector{Tv,Ti}
    n::Int              # Length of the sparse vector
    nzind::Vector{Ti}   # Indices of stored values
    nzval::Vector{Tv}   # Stored values, typically nonzeros
end

As for SparseMatrixCSC, the SparseVector type can also contain explicitly stored zeros. (See Sparse Matrix Storage.).

Sparse Vector and Matrix Constructors

The simplest way to create a sparse array is to use a function equivalent to the zeros function that Julia provides for working with dense arrays. To produce a sparse array instead, you can use the same name with an sp prefix:

julia> spzeros(3)
3-element SparseVector{Float64, Int64} with 0 stored entries

The sparse function is often a handy way to construct sparse arrays. For example, to construct a sparse matrix we can input a vector I of row indices, a vector J of column indices, and a vector V of stored values (this is also known as the COO (coordinate) format). sparse(I,J,V) then constructs a sparse matrix such that S[I[k], J[k]] = V[k]. The equivalent sparse vector constructor is sparsevec, which takes the (row) index vector I and the vector V with the stored values and constructs a sparse vector R such that R[I[k]] = V[k].

julia> I = [1, 4, 3, 5]; J = [4, 7, 18, 9]; V = [1, 2, -5, 3];

julia> S = sparse(I,J,V)
5×18 SparseMatrixCSC{Int64, Int64} with 4 stored entries:
⎡⠀⠈⠀⠀⠀⠀⠀⠀⢀⎤
⎣⠀⠀⠀⠂⡀⠀⠀⠀⠀⎦

julia> R = sparsevec(I,V)
5-element SparseVector{Int64, Int64} with 4 stored entries:
  [1]  =  1
  [3]  =  -5
  [4]  =  2
  [5]  =  3

The inverse of the sparse and sparsevec functions is findnz, which retrieves the inputs used to create the sparse array (including stored entries equal to zero). findall(!iszero, x) returns the Cartesian indices of non-zero entries in x (not including stored entries equal to zero).

julia> findnz(S)
([1, 4, 5, 3], [4, 7, 9, 18], [1, 2, 3, -5])

julia> findall(!iszero, S)
4-element Vector{CartesianIndex{2}}:
 CartesianIndex(1, 4)
 CartesianIndex(4, 7)
 CartesianIndex(5, 9)
 CartesianIndex(3, 18)

julia> findnz(R)
([1, 3, 4, 5], [1, -5, 2, 3])

julia> findall(!iszero, R)
4-element Vector{Int64}:
 1
 3
 4
 5

Another way to create a sparse array is to convert a dense array into a sparse array using the sparse function:

julia> sparse(Matrix(1.0I, 5, 5))
5×5 SparseMatrixCSC{Float64, Int64} with 5 stored entries:
 1.0   ⋅    ⋅    ⋅    ⋅
  ⋅   1.0   ⋅    ⋅    ⋅
  ⋅    ⋅   1.0   ⋅    ⋅
  ⋅    ⋅    ⋅   1.0   ⋅
  ⋅    ⋅    ⋅    ⋅   1.0

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

You can go in the other direction using the Array constructor. The issparse function can be used to query if a matrix is sparse.

julia> issparse(spzeros(5))
true

Sparse matrix operations

Arithmetic operations on sparse matrices also work as they do on dense matrices. Indexing of, assignment into, and concatenation of sparse matrices work in the same way as dense matrices. Indexing operations, especially assignment, are expensive, when carried out one element at a time. In many cases it may be better to convert the sparse matrix into (I,J,V) format using findnz, manipulate the values or the structure in the dense vectors (I,J,V), and then reconstruct the sparse matrix.

Correspondence of dense and sparse methods

The following table gives a correspondence between built-in methods on sparse matrices and their corresponding methods on dense matrix types. In general, methods that generate sparse matrices differ from their dense counterparts in that the resulting matrix follows the same sparsity pattern as a given sparse matrix S, or that the resulting sparse matrix has density d, i.e. each matrix element has a probability d of being non-zero.

Details can be found in the Sparse Vectors and Matrices section of the standard library reference.

Sparse Dense Description

Sparse	Dense	Description
`spzeros(m,n)`	`zeros(m,n)`	Creates a m-by-n matrix of zeros. (`spzeros(m,n)` is empty.)
`sparse(I,n,n)`	`Matrix(I,n,n)`	Creates a n-by-n identity matrix.
`sparse(A)`	`Array(S)`	Interconverts between dense and sparse formats.
`sprand(m,n,d)`	`rand(m,n)`	Creates a m-by-n random matrix (of density d) with iid non-zero elements distributed uniformly on the half-open interval .
`sprandn(m,n,d)`	`randn(m,n)`	Creates a m-by-n random matrix (of density d) with iid non-zero elements distributed according to the standard normal (Gaussian) distribution.
`sprandn(rng,m,n,d)`	`randn(rng,m,n)`	Creates a m-by-n random matrix (of density d) with iid non-zero elements generated with the `rng` random number generator

spzeros(m,n)

zeros(m,n)

Creates a m-by-n matrix of zeros. (spzeros(m,n) is empty.)

sparse(I,n,n)

Matrix(I,n,n)

Creates a n-by-n identity matrix.

sparse(A)

Array(S)

Interconverts between dense and sparse formats.

sprand(m,n,d)

rand(m,n)

Creates a m-by-n random matrix (of density d) with iid non-zero elements distributed uniformly on the half-open interval .

sprandn(m,n,d)

randn(m,n)

Creates a m-by-n random matrix (of density d) with iid non-zero elements distributed according to the standard normal (Gaussian) distribution.

sprandn(rng,m,n,d)

randn(rng,m,n)

Creates a m-by-n random matrix (of density d) with iid non-zero elements generated with the rng random number generator

SparseArrays API

# SparseArrays.AbstractSparseArray — Type

AbstractSparseArray{Tv,Ti,N}

Супертип для N-мерных разреженных массивов (или массивоподобных типов) с элементами типа Tv и типом индекса Ti. Подтипами данного типа являются SparseMatrixCSC, SparseVector и SuiteSparse.CHOLMOD.Sparse.

# SparseArrays.AbstractSparseVector — Type

AbstractSparseVector{Tv,Ti}

Супертип для одномерных разреженных массивов (или массивоподобных типов) с элементами типа Tv и типом индекса Ti. Псевдоним для AbstractSparseArray{Tv,Ti,1}.

# SparseArrays.AbstractSparseMatrix — Type

AbstractSparseMatrix{Tv,Ti}

Супертип для двумерных разреженных массивов (или массивоподобных типов) с элементами типа Tv и типом индекса Ti. Псевдоним для AbstractSparseArray{Tv,Ti,2}.

# SparseArrays.SparseVector — Type

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

Векторный тип для хранения разреженных векторов. Может быть создан путем передачи длины вектора, отсортированного вектора ненулевых индексов и вектора ненулевых значений.

Например, вектор [5, 6, 0, 7] может быть представлен в следующем виде:

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

Это значит, что элемент с индексом 1 имеет значение 5, с индексом 2 — значение 6, с индексом 3 — значение zero(Int), а с индексом 4 — значение 7.

Разреженные векторы может быть удобнее создавать напрямую из плотных векторов с помощью sparse, так как

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

выдает тот же разреженный вектор.

# SparseArrays.SparseMatrixCSC — Type

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

Матричный тип для хранения разреженных матриц в формате сжатых разреженных столбцов. Стандартный способ создания SparseMatrixCSC — с помощью функции sparse. См. также описание spzeros, spdiagm и sprand.

# SparseArrays.sparse — Function

sparse(A)

Преобразовывает объект AbstractMatrix A в разреженную матрицу.

Примеры

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.0

julia> sparse(A)
3×3 SparseMatrixCSC{Float64, Int64} with 3 stored entries:
 1.0   ⋅    ⋅
  ⋅   1.0   ⋅
  ⋅    ⋅   1.0

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

Создает разреженную матрицу S размером m x n такую, что S[I[k], J[k]] = V[k]. Функция combine используется для объединения дубликатов. Если m и n не указаны, им присваиваются значения maximum(I) и maximum(J) соответственно. Если функция combine не предоставлена, в качестве combine по умолчанию используется +, если только элементы V не являются логическими значениями. В этом случае по умолчанию в качестве combine используется |. Все элементы I должны отвечать условию 1 <= I[k] <= m, а все элементы J — условию 1 <= J[k] <= n. Числовые нули в (I, J, V) сохраняются как структурные ненулевые значения; для удаления числовых нулей используйте dropzeros!.

Дополнительную документацию и рекомендации см. в описании функции SparseArrays.sparse!.

Примеры

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

# SparseArrays.sparse! — Function

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}

Родительский объект для sparse, рекомендованный к использованию; основное использование см. в описании sparse. Этот метод позволяет пользователю предварительно выделять память для промежуточных объектов и результата sparse, как описано ниже. Данная возможность позволяет более эффективно последовательно создавать SparseMatrixCSC на основе координатных представлений, а также обеспечивает извлечение представления без сортировки столбцов для полученного транспонирования без дополнительных затрат.

Данный метод выполняется в три основных этапа: 1) Выполняет сортировку подсчетом предоставленного координатного представления в форме CSR без сортировки строк, включая повторяющиеся элементы. 2) Выполняет прогонку по форме CSR, одновременно вычисляя нужный массив указателей на столбцы для формы CSC, обнаруживая повторяющиеся элементы и повторно упаковывая форму CSR с объединением повторяющихся элементов. На этом этапе выдается форма CSR без сортировки строк и без повторяющихся элементов. 3) Выполняет сортировку подсчетом предыдущей формы CSR для получения полностью отсортированной формы CSC без повторяющихся элементов.

Входные массивы csrrowptr, csrcolval и csrnzval образуют хранилище для промежуточных форм CSR и требуют соблюдения условий length(csrrowptr) >= m + 1, length(csrcolval) >= length(I) и length(csrnzval >= length(I)). Входной массив klasttouch, рабочее пространство для второго этапа, требует соблюдения условия length(klasttouch) >= n. Необязательные входные массивы csccolptr, cscrowval и cscnzval образуют хранилище для возвращаемой формы CSC S. При необходимости их размер изменяется автоматически для выполнения условий length(csccolptr) = n + 1, length(cscrowval) = nnz(S) и length(cscnzval) = nnz(S). Поэтому если значение nnz(S) изначально неизвестно, достаточно передать пустые векторы соответствующего типа (Vector{Ti}() и Vector{Tv}() соответственно) или вызвать метод sparse!, игнорируя cscrowval и cscnzval.

При возврате управления csrrowptr, csrcolval и csrnzval будут содержать представление без сортировки столбцов для полученного транспонирования.

Память, выделенную для входных массивов (I, J, V), можно использовать повторно для выходных массивов (csccolptr, cscrowval, cscnzval). Например, можно вызвать sparse!(I, J, V, csrrowptr, csrcolval, csrnzval, I, J, V). Обратите внимание, что их размер будет изменен для выполнения указанных выше условий.

В целях повышения эффективности этот метод не выполняет проверок аргументов, кроме 1 <= I[k] <= m и 1 <= J[k] <= n. Используйте его с осторожностью. Тестирование с --check-bounds=yes будет нелишним.

Этот метод выполняется за время O(m, n, length(I)). На использование в этом методе двух сортировок подсчетом вдохновил алгоритм HALFPERM, описанный в работе Ф. Густавсона (F. Gustavson) Two fast algorithms for sparse matrices: multiplication and permuted transposition, ACM TOMS 4(3), 250-269 (1978).

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

Вариант sparse! с повторным использованием входных векторов (I, J, V) для хранения итоговой матрицы. После создания входные векторы будут являться псевдонимами для матричных буферов (будет верно S.colptr === I, S.rowval === J и S.nzval === V), и при необходимости их размер будет изменен с помощью resize!.

Обратите внимание, что все равно выделяются рабочие буферы. В частности, этот метод является удобной оболочкой для sparse!(I, J, V, m, n, combine, klasttouch, csrrowptr, csrcolval, csrnzval, csccolptr, cscrowval, cscnzval), где он выделяет klasttouch, csrrowptr, csrcolval и csrnzval соответствующих размеров, но повторно использует I, J и V для csccolptr, cscrowval и cscnzval.

Аргументы m, n и combine по умолчанию равны maximum(I), maximum(J) и + соответственно.

Совместимость

Julia 1.10 Для этого метода требуется версия Julia не ниже 1.10.

# SparseArrays.sparsevec — Function

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

Создает разреженный вектор S длиной m такой, что S[I[k]] = V[k]. Дубликаты объединяются с помощью функции combine, в качестве которой по умолчанию используется +, если аргумент combine не указан. Исключением является случай, когда элементы V представляют собой логические значения. В этом случае по умолчанию в качестве combine используется |.

Примеры

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.2

julia> sparsevec(II, V, 8, -)
8-element SparseVector{Float64, Int64} with 3 stored entries:
  [1]  =  0.1
  [3]  =  -0.1
  [5]  =  0.2

julia> 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(A)

Преобразовывает вектор A в разреженный вектор длиной m.

Примеры

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

sparsevec(A)

Convert a vector A into a sparse vector of length m. Numerical zeros in A 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

# Base.similar — Method

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

Создать неинициализированный изменяемый массив с заданным типом элементов, типом индекса и размером на основе заданного источника SparseMatrixCSC. Новая разреженная матрица сохраняет структуру исходной разреженной матрицы, за исключением случаев, когда размеры выходной матрицы отличаются от исходных.

Выходная матрица содержит нули в тех же местах, что и входная, но неинициализированные значения в местах, отличных от нуля.

# SparseArrays.issparse — Function

issparse(S)

Возвращает true, если S является разреженным, и false в противном случае.

Примеры

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

julia> issparse(sv)
true

julia> issparse(Array(sv))
false

# SparseArrays.nnz — Function

nnz(A)

Возвращает количество хранимых (добавленных) элементов в разреженном массиве.

Примеры

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

julia> nnz(A)
3

# SparseArrays.findnz — Function

findnz(A::SparseMatrixCSC)

Возвращает кортеж (I, J, V), где I и J — это индексы строк и столбцов хранимых («структурных ненулевых») значений в разреженной матрице A, а V — вектор значений.

Примеры

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])

# SparseArrays.spzeros — Function

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

Создает разреженный вектор длиной m или разреженную матрицу размером m x n. Этот разреженный массив не будет содержать ненулевых значений. Во время создания память для хранения ненулевых значений не выделяется. Если тип не указан, по умолчанию используется Float64.

Примеры

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])

Создает разреженную матрицу S размером m x n со структурными нулями в S[I[k], J[k]].

Этот метод можно использовать для построения шаблона разреженности матрицы, и он более эффективен, чем, например, вызов sparse(I, J, zeros(length(I))).

Дополнительную документацию и рекомендации см. в описании функции SparseArrays.spzeros!.

Совместимость

Julia 1.10 Для этого метода требуется версия Julia не ниже 1.10.

# SparseArrays.spzeros! — Function

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}

Родительский объект для spzeros(I, J), рекомендованный к использованию; позволяет пользователю предварительно выделять память для промежуточных объектов. Этот метод соотносится со spzeros так же, как SparseArrays.sparse! со sparse. Подробные сведения и требуемые длины буферов см. в документации по SparseArrays.sparse!.

Совместимость

Julia 1.10 Для этого метода требуется версия Julia не ниже 1.10.

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

Вариант spzeros! с повторным использованием входных векторов I и J для хранения итоговой матрицы. После создания входные векторы будут являться псевдонимами для матричных буферов (будет верно S.colptr === I и S.rowval === J), и при необходимости их размер будет изменен с помощью resize!.

Обратите внимание, что все равно выделяются рабочие буферы. В частности, этот метод является удобной оболочкой для spzeros!(Tv, I, J, m, n, klasttouch, csrrowptr, csrcolval, csccolptr, cscrowval), где он выделяет klasttouch, csrrowptr и csrcolval соответствующих размеров, но повторно использует I и J для csccolptr и cscrowval.

Аргументы m и n по умолчанию равны maximum(I) и maximum(J) соответственно.

Совместимость

Julia 1.10 Для этого метода требуется версия Julia не ниже 1.10.

# SparseArrays.spdiagm — Function

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

Создает разреженную диагональную матрицу из пар (Pair) векторов и диагоналей. Каждый вектор kv.second будет размещен на диагонали kv.first. По умолчанию матрица квадратная, и ее размер выводится из kv, но можно задать неквадратную матрицу размером m×n (с заполнением нулями по мере необходимости), передав m,n в качестве первых аргументов.

Примеры

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)

Создает разреженную матрицу, диагональными элементами которой являются элементы вектора. По умолчанию (если m и n не указаны) матрица квадратная, и ее размер задается с помощью length(v), но можно задать неквадратную матрицу размером m×n, передав m и n в качестве первых аргументов.

Совместимость

Julia 1.6 Для этих функций требуется версия Julia не ниже 1.6.

Примеры

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

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

# SparseArrays.sparse_hcat — Function

sparse_hcat(A...)

Выполняет конкатенацию в измерении 2. Возвращает объект SparseMatrixCSC.

Совместимость

Julia 1.8 Этот метод был добавлен в Julia 1.8. Он воспроизводит предыдущее поведение конкатенации, которое заключалось в том, что конкатенация со специализированными «разреженными» типами матриц из LinearAlgebra.jl автоматически давала разреженный результат даже при отсутствии аргумента SparseArray.

# SparseArrays.sparse_vcat — Function

sparse_vcat(A...)

Выполняет конкатенацию в измерении 1. Возвращает объект SparseMatrixCSC.

Совместимость

# SparseArrays.sparse_hvcat — Function

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

Разреженная горизонтальная и вертикальная конкатенация в одном вызове. Эта функция вызывается для синтаксиса блочной матрицы. Первый аргумент задает количество аргументов для конкатенации в каждой строке блока.

Совместимость

# SparseArrays.blockdiag — Function

blockdiag(A...)

Выполняет конкатенацию матриц поблочно по диагонали. В настоящее время реализовано только для разреженных матриц.

Примеры

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

# SparseArrays.sprand — Function

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

Создает разреженный вектор случайной длины m или разреженную матрицу размером m на n, в которых вероятность того, что любой элемент является ненулевым, задается независимо с помощью p (и поэтому средняя плотность ненулевых значений всегда равна p). В необязательном аргументе rng указывается генератор случайных чисел; см. раздел Случайные числа. В необязательном аргументе T указывается тип элементов, по умолчанию Float64.

По умолчанию ненулевые значения выбираются из равномерного распределения с помощью функции rand, то есть посредством вызова rand(T) или, если указано значение rng, rand(rng, T). При значении по умолчанию T=Float64 это соответствует равномерной выборке ненулевых значений в интервале [0,1).

Для выборки ненулевых значений из другого распределения передайте пользовательскую функцию rfn вместо rand. Эта функция rfn(k) должна возвращать массив из k случайных чисел, выбранных из нужного распределения. Если же задан аргумент rng, это должна быть функция rfn(rng, k).

Примеры

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

# SparseArrays.sprandn — Function

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

Создает случайный разреженный вектор длиной m или разреженную матрицу размером m на n, в которых каждый элемент является ненулевым с указанной (независимой) вероятностью p, а ненулевые значения выбираются из нормального распределения. В необязательном аргументе rng указывается генератор случайных чисел; см. раздел Случайные числа.

Совместимость

Julia 1.1 Для указания типа выходных элементов Type требуется версия Julia не ниже 1.1.

Примеры

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

# SparseArrays.nonzeros — Function

nonzeros(A)

Возвращает вектор структурных ненулевых значений в разреженном массиве A. Сюда включаются нули, сохраненные в разреженном массиве явным образом. Возвращаемый вектор указывает непосредственно на внутреннее ненулевое хранилище A, а любое изменение возвращаемого вектора приводит также к изменению A. См. описание rowvals и nzrange.

Примеры

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

julia> nonzeros(A)
3-element Vector{Int64}:
 2
 2
 2

# SparseArrays.rowvals — Function

rowvals(A::AbstractSparseMatrixCSC)

Возвращает вектор индексов строк A. Любое изменение возвращаемого вектора приводит также к изменению A. Доступ к внутренней информации о том, как хранятся индексы строк, может быть полезен в связи с итерацией по структурным ненулевым значениям. См. также описание nonzeros и nzrange.

Примеры

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

julia> rowvals(A)
3-element Vector{Int64}:
 1
 2
 3

# SparseArrays.nzrange — Function

nzrange(A::AbstractSparseMatrixCSC, col::Integer)

Возвращает диапазон индексов структурных ненулевых значений в столбце разреженной матрицы. В сочетании с nonzeros и rowvals это обеспечивает удобную итерацию по разреженной матрице:

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] # операции с разреженной матрицей... end end

Warning Добавление ненулевых элементов в матрицу или их удаление может привести к тому, что nzrange станет недействительным. Во время итерации матрицу изменять не следует.

nzrange(x::SparseVectorUnion, col)

Возвращает диапазон индексов структурных ненулевых значений в разреженном векторе. Индекс столбца col игнорируется (предполагается значение 1).

# SparseArrays.droptol! — Function

droptol!(A::AbstractSparseMatrixCSC, tol)

Удаляет из A хранимые значения, абсолютное значение которых не превышает tol.

droptol!(x::AbstractCompressedVector, tol)

Удаляет из x хранимые значения, абсолютное значение которых не превышает tol.

# SparseArrays.dropzeros! — Function

dropzeros!(x::AbstractCompressedVector)

Удаляет из x хранимые числовые нули.

Если удаление должно производиться не на месте, используйте версию dropzeros. Информацию об алгоритме работы см. в описании функции fkeep!.

# SparseArrays.dropzeros — Function

dropzeros(A::AbstractSparseMatrixCSC;)

Создает копию A и удаляет из нее хранимые числовые нули.

Информацию об алгоритме работы см. в описании функции dropzeros!, которая является версией данной функции, выполняемой на месте.

Примеры

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.0

julia> dropzeros(A)
3×3 SparseMatrixCSC{Float64, Int64} with 2 stored entries:
 1.0   ⋅    ⋅
  ⋅    ⋅    ⋅
  ⋅    ⋅   1.0

dropzeros(x::AbstractCompressedVector)

Создает копию x и удаляет из нее числовые нули.

Примеры

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.0

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

# SparseArrays.permute — Function

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

Выполняет двустороннюю перестановку A, возвращая PAQ (A[p,q]). Длина перестановки столбцов q должна быть равной числу столбцов в A (length(q) == size(A, 2)). Длина перестановки строк p должна быть равной числу строк в A (length(p) == size(A, 1)).

Рекомендации и дополнительную информацию см. в описании функции permute!.

Примеры

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
 ⋅  ⋅  ⋅  4

julia> 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  ⋅  ⋅  ⋅

# Base.permute! — Method

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

Выполняет двустороннюю перестановку A, сохраняя результат PAQ (A[p,q]) в X. Сохраняет промежуточный результат (AQ)^T (transpose(A[:,q])) в необязательном аргументе C, если он указан. Аргументы X, A и (при наличии) C не должны быть псевдонимами друг друга. Для сохранения результата PAQ обратно в A используйте следующий метод без X:

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

Измерения X должны соответствовать измерениям A (size(X, 1) == size(A, 1) и size(X, 2) == size(A, 2)), а в X должно быть достаточно места для хранения всех элементов в A, для которых выделена память (length(rowvals(X)) >= nnz(A) и length(nonzeros(X)) >= nnz(A)). Длина перестановки столбцов q должна быть равной числу столбцов в A (length(q) == size(A, 2)). Длина перестановки строк p должна быть равной числу строк в A (length(p) == size(A, 1)).

Измерения C должны соответствовать измерениям transpose(A) (size(C, 1) == size(A, 2) и size(C, 2) == size(A, 1)), а в C должно быть достаточно места для хранения всех элементов в A, для которых выделена память (length(rowvals(C)) >= nnz(A) и length(nonzeros(C)) >= nnz(A)).

Дополнительную информацию об алгоритме работы и о версиях этих методов без проверки аргументов см. в описании (неэкспортируемых) родительских методов unchecked_noalias_permute! и unchecked_aliasing_permute!.

См. также описание permute.

# SparseArrays.halfperm! — Function

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

Выполняет перестановку столбцов и транспонирование матрицы A, одновременно применяя f к каждому элементу A и сохраняя результат (f(A)Q)^T (map(f, transpose(A[:,q]))) в X.

Тип элементов Tv матрицы X должен соответствовать f(::TvA), где TvA — это тип элементов матрицы A. Измерения X должны соответствовать измерениям transpose(A) (size(X, 1) == size(A, 2) и size(X, 2) == size(A, 1)), а в X должно быть достаточно места для хранения всех элементов в A, для которых выделена память (length(rowvals(X)) >= nnz(A) и length(nonzeros(X)) >= nnz(A)). Длина перестановки столбцов q должна быть равной числу столбцов в A (length(q) == size(A, 2)).

Этот метод является родительским для ряда методов, выполняющих операции транспонирования и перестановки SparseMatrixCSC. Так как он не предполагает проверки аргументов, для использования лучше предпочесть более безопасные дочерние методы ([c]transpose[!], permute[!]).

Этот метод реализует алгоритм HALFPERM, описанный в работе Ф. Густавсона (F. Gustavson) Two fast algorithms for sparse matrices: multiplication and permuted transposition, ACM TOMS 4(3), 250-269 (1978). Алгоритм выполняется за время O(size(A, 1), size(A, 2), nnz(A)) и не требует дополнительного места, помимо занимаемого входными данными.

# SparseArrays.ftranspose! — Function

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

Выполняет транспонирование матрицы A и сохраняет ее в X, одновременно применяя функцию f к ненулевым элементам. Нулевые элементы, создаваемые функцией f, не удаляются. size(X) должно быть равно size(transpose(A)). Дополнительная память, помимо изменения размера rowval и nzval для X (если это необходимо), не выделяется.

См. описание halfperm!.

Noteworthy External Sparse Packages

Several other Julia packages provide sparse matrix implementations that should be mentioned:

SuiteSparseGraphBLAS.jl is a wrapper over the fast, multithreaded SuiteSparse:GraphBLAS C library. On CPU this is typically the fastest option, often significantly outperforming MKLSparse.
CUDA.jl exposes the CUSPARSE library for GPU sparse matrix operations.
SparseMatricesCSR.jl provides a Julia native implementation of the Compressed Sparse Rows (CSR) format.
MKLSparse.jl accelerates SparseArrays sparse-dense matrix operations using Intel’s MKL library.
SparseArrayKit.jl available for multidimensional sparse arrays.
LuxurySparse.jl provides static sparse array formats, as well as a coordinate format.
ExtendableSparse.jl enables fast insertion into sparse matrices using a lazy approach to new stored indices.
Finch.jl supports extensive multidimensional sparse array formats and operations through a mini tensor language and compiler, all in native Julia. Support for COO, CSF, CSR, CSC and more, as well as operations like broadcast, reduce, etc. and custom operations.

External packages providing sparse direct solvers:

External packages providing solvers for iterative solution of eigensystems and singular value decompositions:

External packages for working with graphs:

Graphs.jl