This package is switching to an array interface, compatible with NumPy arrays, from the older matrix interface. We recommend that you use the array objects
(bsr_array, coo_array, etc.) for all new work.
When using the array interface, please note that:
x*y no longer performs
matrix multiplication, but element-wise multiplication (just like with NumPy arrays). To make code work with both arrays and matrices, use x@y for matrix multiplication.
Operations such as sum, that used to produce dense matrices, now produce arrays, whose multiplication behavior differs similarly.
Sparse arrays currently must be two-dimensional. This also means that all slicing operations on these objects must produce two-dimensional results,
or they will result in an error. This will be addressed in a future version.
The construction utilities (eye, kron,
random, diags, etc.) have not yet been ported, but their results can be wrapped into arrays:
Contents#
Sparse array classes#
bsr_array(arg1[, shape, dtype, copy, blocksize])
Block Sparse Row array
coo_array(arg1[, shape, dtype, copy])
A sparse array in COOrdinate format.
csc_array(arg1[, shape, dtype, copy])
Compressed Sparse Column array
csr_array(arg1[, shape, dtype, copy])
Compressed Sparse Row array
dia_array(arg1[, shape, dtype, copy])
Sparse array with DIAgonal storage
dok_array(arg1[, shape, dtype, copy])
Dictionary Of Keys based sparse array.
lil_array(arg1[, shape, dtype, copy])
Row-based list of lists sparse array
Sparse matrix classes#
bsr_matrix(arg1[, shape, dtype, copy, blocksize])
Block Sparse Row matrix
coo_matrix(arg1[, shape, dtype, copy])
A sparse matrix in COOrdinate format.
csc_matrix(arg1[, shape, dtype, copy])
Compressed Sparse Column matrix
csr_matrix(arg1[, shape, dtype, copy])
Compressed Sparse Row matrix
dia_matrix(arg1[, shape, dtype, copy])
Sparse matrix with DIAgonal storage
dok_matrix(arg1[, shape, dtype, copy])
Dictionary Of Keys based sparse matrix.
lil_matrix(arg1[, shape, dtype, copy])
Row-based list of lists sparse matrix
spmatrix([maxprint])
This class provides a base class for all sparse matrices.
Functions#
Building sparse matrices:
eye(m[, n, k, dtype, format])
Sparse matrix with ones on diagonal
identity(n[, dtype, format])
Identity matrix in sparse format
kron(A, B[, format])
kronecker product of sparse matrices A and B
kronsum(A, B[, format])
kronecker sum of sparse matrices A and B
diags(diagonals[, offsets, shape, format, dtype])
Construct a sparse matrix from diagonals.
spdiags(data, diags[, m, n, format])
Return a sparse matrix from diagonals.
block_diag(mats[, format, dtype])
Build a block diagonal sparse matrix from provided matrices.
tril(A[, k, format])
Return the lower triangular portion of a matrix in sparse format
triu(A[, k, format])
Return the upper triangular portion of a matrix in sparse format
bmat(blocks[, format, dtype])
Build a sparse matrix from sparse sub-blocks
hstack(blocks[, format, dtype])
Stack sparse matrices horizontally (column wise)
vstack(blocks[, format, dtype])
Stack sparse matrices vertically (row wise)
rand(m, n[, density, format, dtype, ...])
Generate a sparse matrix of the given shape and density with uniformly distributed values.
random(m, n[, density, format, dtype, ...])
Generate a sparse matrix of the given shape and density with randomly distributed values.
Save and load sparse matrices:
save_npz(file, matrix[, compressed])
Save a sparse matrix to a file using .npz format.
load_npz(file)
Load a sparse matrix from a file using .npz format.
Sparse matrix tools:
find(A)
Return the indices and values of the nonzero elements of a matrix
coo_matrix: COOrdinate format (aka IJV, triplet format)
dia_matrix: DIAgonal format
To construct a matrix efficiently, use either dok_matrix or lil_matrix. The lil_matrix class supports basic slicing and fancy indexing with a similar syntax to NumPy arrays. As illustrated below, the COO format may also be used to efficiently construct matrices. Despite their
similarity to NumPy arrays, it is strongly discouraged to use NumPy functions directly on these matrices because NumPy may not properly convert them for computations, leading to unexpected (and incorrect) results. If you do want to apply a NumPy function to these matrices, first check if SciPy has its own implementation for the given sparse matrix class, or convert the sparse matrix to a NumPy array (e.g., using the toarray() method of the class) first
before applying the method.
To perform manipulations such as multiplication or inversion, first convert the matrix to either CSC or CSR format. The lil_matrix format is row-based, so conversion to CSR is efficient, whereas conversion to CSC is less so.
All conversions among the CSR, CSC, and COO formats are efficient, linear-time operations.
Matrix vector
product#
To do a vector product between a sparse matrix and a vector simply use the matrix dot method, as described in its docstring:
As of NumPy 1.7, np.dot is not aware of sparse matrices, therefore using it will result on unexpected results or errors. The corresponding dense array
should be obtained first instead:
This is useful for constructing finite-element stiffness and mass matrices.
Further details#
CSR column indices are not necessarily sorted. Likewise for CSC row
indices. Use the .sorted_indices() and .sort_indices() methods when sorted indices are required (e.g., when passing data to other libraries).