Sparse arrays (scipy.sparse)#
SciPy 2-D sparse array package for numeric data.
Note
This package is switching to an array interface, compatible withNumPy arrays, from the older matrix interface. We recommend thatyou use the array objects (bsr_array,coo_array, etc.) forall new work.
When using the array interface, please note that:
x*yno longer performs matrix multiplication, butelement-wise multiplication (just like with NumPy arrays). Tomake code work with both arrays and matrices, usex@yformatrix multiplication.Operations such as
sum, that used to produce dense matrices, nowproduce arrays, whose multiplication behavior differs similarly.Sparse arrays use array styleslicing operations, returning scalars,1D, or 2D sparse arrays. If you need 2D results, use an appropriate index.E.g.
A[:,i,None]orA[:,[i]].All index arrays for a given sparse array should be of same dtype.For example, for CSR format,
indicesandindptrshould havethe same dtype. For COO, each array incoords should have same dtype.
The construction utilities (eye,kron,random,diags, etc.)have appropriate replacements (seeBuilding sparse arrays).
For more information seeMigration from spmatrix to sparray.
Submodules#
Sparse array classes#
| Block Sparse Row format sparse array. |
| A sparse array in COOrdinate format. |
| Compressed Sparse Column array. |
| Compressed Sparse Row array. |
| Sparse array with DIAgonal storage. |
| Dictionary Of Keys based sparse array. |
| Row-based LIst of Lists sparse array. |
| This class provides a base class for all sparse arrays. |
Building sparse arrays#
| Construct a sparse array from diagonals. |
| Sparse array of chosen shape with ones on the kth diagonal and zeros elsewhere. |
| Return a sparse array of uniformly random numbers in [0, 1) |
| Build a sparse array from sparse sub-blocks |
Combining arrays#
| Sparse representation of the Kronecker product ofA andB |
| Kronecker sum of square sparse matricesA andB |
| Build a block diagonal sparse matrix or array from provided matrices. |
| Return the lower triangular portion of a sparse array or matrix |
| Return the upper triangular portion of a sparse array or matrix |
| Stack sparse matrices horizontally (column wise) |
| Stack sparse arrays vertically (row wise) |
| Interchange two axes of an array. |
| Add trivial axes to an array. |
| Permute the axes of the sparse arrayA to the orderaxes. |
Sparse tools#
| Save a sparse matrix or array to a file using |
| Load a sparse array/matrix from a file using |
| Return the indices and values of the nonzero elements of a matrix |
| Based on input (integer) arraysa, determine a suitable index data type that can hold the data in the arrays. |
| Safely cast sparse array indices toidx_dtype. |
Identifying sparse arrays#
| Isx of a sparse array or sparse matrix type? |
Sparse matrix classes#
| Block Sparse Row format sparse matrix. |
| A sparse matrix in COOrdinate format. |
| Compressed Sparse Column matrix. |
| Compressed Sparse Row matrix. |
| Sparse matrix with DIAgonal storage. |
| Dictionary Of Keys based sparse matrix. |
| Row-based LIst of Lists sparse matrix. |
| This class provides a base class for all sparse matrix classes. |
Building sparse matrices#
| Sparse matrix of chosen shape with ones on the kth diagonal and zeros elsewhere. |
| Identity matrix in sparse format |
| Construct a sparse matrix from diagonals. |
| Return a sparse matrix from diagonals. |
| Build a sparse array or matrix from sparse sub-blocks |
| Generate a sparse matrix of the given shape and density with randomly distributed values. |
| Generate a sparse matrix of the given shape and density with uniformly distributed values. |
Combining matrices use the same functions as forCombining arrays.
Identifying sparse matrices#
| Isx of a sparse array or sparse matrix type? |
| Isx of a sparse matrix type? |
Isx of csc_matrix type? | |
Isx of csr_matrix type? | |
Isx of a bsr_matrix type? | |
Isx of lil_matrix type? | |
Isx of dok_array type? | |
Isx of coo_matrix type? | |
Isx of dia_matrix type? |
Warnings#
The warning emitted when the operation is inefficient for sparse matrices. | |
General warning for |
Usage information#
There are seven available sparse array types:
csc_array: Compressed Sparse Column format
csr_array: Compressed Sparse Row format
bsr_array: Block Sparse Row format
lil_array: List of Lists format
dok_array: Dictionary of Keys format
coo_array: COOrdinate format (aka IJV, triplet format)
dia_array: DIAgonal format
To construct an array efficiently, use any ofcoo_array,dok_array orlil_array.dok_array andlil_arraysupport basic slicing and fancy indexing with a similar syntaxto NumPy arrays. The COO format does not support indexing (yet)but can also be used to efficiently construct arrays using coordand value info.
Despite their similarity to NumPy arrays, it isstrongly discouragedto use NumPy functions directly on these arrays because NumPy typicallytreats them as generic Python objects rather than arrays, leading tounexpected (and incorrect) results. If you do want to apply a NumPyfunction to these arrays, first check if SciPy has its own implementationfor the given sparse array class, orconvert the sparse array toa NumPy array (e.g., using thetoarray method of the class)before applying the method.
All conversions among the CSR, CSC, and COO formats are efficient,linear-time operations.
To perform manipulations such as multiplication or inversion, firstconvert the array to either CSC or CSR format. Thelil_arrayformat is row-based, so conversion to CSR is efficient, whereasconversion to CSC is less so.
Matrix vector product#
To do a vector product between a 2D sparse array and a vector usethe matmul operator (i.e.,@) which performs a dot product (like thedot method):
>>>importnumpyasnp>>>fromscipy.sparseimportcsr_array>>>A=csr_array([[1,2,0],[0,0,3],[4,0,5]])>>>v=np.array([1,0,-1])>>>A@varray([ 1, -3, -1], dtype=int64)
The CSR format is especially suitable for fast matrix vector products.
Example 1#
Construct a 1000x1000lil_array and add some values to it:
>>>fromscipy.sparseimportlil_array>>>fromscipy.sparse.linalgimportspsolve>>>fromnumpy.linalgimportsolve,norm>>>fromnumpy.randomimportrand
>>>A=lil_array((1000,1000))>>>A[0,:100]=rand(100)>>>A.setdiag(rand(1000))
Now convert it to CSR format and solve A x = b for x:
>>>A=A.tocsr()>>>b=rand(1000)>>>x=spsolve(A,b)
Convert it to a dense array and solve, and check that the resultis the same:
>>>x_=solve(A.toarray(),b)
Now we can compute norm of the error with:
>>>err=norm(x-x_)>>>err<1e-9True
It should be small :)
Example 2#
Construct an array in COO format:
>>>fromscipyimportsparse>>>fromnumpyimportarray>>>I=array([0,3,1,0])>>>J=array([0,3,1,2])>>>V=array([4,5,7,9])>>>A=sparse.coo_array((V,(I,J)),shape=(4,4))
Notice that the indices do not need to be sorted.
Duplicate (i,j) entries are summed when converting to CSR or CSC.
>>>I=array([0,0,1,3,1,0,0])>>>J=array([0,2,1,3,1,0,0])>>>V=array([1,1,1,1,1,1,1])>>>B=sparse.coo_array((V,(I,J)),shape=(4,4)).tocsr()
This is useful for constructing finite-element stiffness and mass matrices.
Further details#
CSR column indices are not necessarily sorted. Likewise for CSC rowindices. Use the.sorted_indices() and.sort_indices() methods whensorted indices are required (e.g., when passing data to other libraries).