Sparse arrays (cupyx.scipy.sparse)#

Hint

SciPy API Reference: Sparse arrays (scipy.sparse)

CuPy sparse array package for numeric data, matching SciPy’s sparse package. It builds on cuSPARSE for high-performance sparse linear algebra on the GPU. Refer to the SciPy documentation for usage; the sections below cover the CuPy-specific differences.

Note

Prefer the sparse array classes (*_array) for new code. They are new in CuPy and follow NumPy-like semantics (* is element-wise; use @ for matrix multiplication). SciPy plans to deprecate sparse matrices (*_matrix) in favor of sparse arrays and CuPy will follow. When porting existing code, see SciPy’s Migration from spmatrix to sparray guide.

CuPy differences from SciPy#

  • Formats: COO, CSR, CSC, and DIA only (no BSR, DOK, or LIL).

  • Dimensions: 2-D for all formats, plus 1-D for coo_array and csr_array. There is no n-D support, and hence no expand_dims.

  • Data dtypes: bool, float32, float64, complex64, and complex128, matching what cuSPARSE supports. SciPy additionally supports the integer dtypes and the extended-precision longdouble / clongdouble.

  • save_npz / load_npz are not implemented.

Index dtype (int32 / int64)#

Like SciPy, CuPy sparse objects automatically choose the index dtype (indices, indptr, row, col) based on the dimensions and index values:

  • int32 when all index values and dimensions fit in a 32-bit integer (the common case).

  • int64 when any dimension or index value exceeds 2**31 - 1.

The dtype is chosen by get_index_dtype() (mirroring SciPy’s logic) and is preserved through format conversions, arithmetic, and indexing. As in SciPy, sparse array constructors keep the dtype of index arrays you pass in, while sparse matrix constructors may downcast int64 indices to int32 when the values fit.

Operations that delegate to cuSPARSE use the native Generic API (SpMatDescr) for int64 where available, with pure-CuPy fallbacks for legacy int32-only APIs (e.g., csr2cscEx2, xcoo2csr, csrgeam2).

Known limitations#

The following operations are int32-only and raise ValueError when called on a sparse object with int64 indices:

Conversion to/from SciPy#

CuPy and SciPy sparse objects are not implicitly convertible. SciPy functions cannot take cupyx.scipy.sparse objects as inputs, and vice versa.

  • To convert SciPy sparse arrays/matrices to CuPy, pass them to the matching CuPy constructor such as csr_array or csr_matrix.

  • To convert CuPy sparse objects to SciPy, use their get() method. Array instances return a SciPy *_array; matrix instances return a SciPy *_matrix.

Converting between CuPy and SciPy incurs host-device data transfer, which is costly.

Conversion to/from CuPy ndarrays#

  • To convert a CuPy ndarray to a sparse object, pass it to a sparse constructor such as csr_array.

  • To convert a sparse object to a dense CuPy ndarray, use toarray().

Converting between CuPy ndarray and CuPy sparse objects does not incur host-device transfer; the data stays on the GPU.

Contents#

Sparse array classes#

coo_array(arg1[, shape, dtype, copy, maxprint])

COOrdinate format sparse array.

csc_array(arg1[, shape, dtype, copy, maxprint])

Compressed Sparse Column array.

csr_array(arg1[, shape, dtype, copy, maxprint])

Compressed Sparse Row array.

dia_array(arg1[, shape, dtype, copy, maxprint])

Sparse array with DIAgonal storage.

sparray()

Base class shared by all sparse array classes.

Sparse matrix classes#

coo_matrix(*args[, maxprint])

COOrdinate format sparse matrix.

csc_matrix(*args[, maxprint])

Compressed Sparse Column matrix.

csr_matrix(*args[, maxprint])

Compressed Sparse Row matrix.

dia_matrix(*args[, maxprint])

Sparse matrix with DIAgonal storage.

spmatrix(*args[, maxprint])

Base class shared by all sparse matrix classes.

Building sparse arrays#

eye_array(m[, n, k, dtype, format])

Creates a sparse array with ones on diagonal.

diags_array(diagonals, /, *[, offsets, ...])

Construct a sparse array from diagonals.

block_array(blocks, *[, format, dtype])

Build a sparse array from sparse sub-blocks.

random_array(shape, *[, density, format, ...])

Generate a sparse random array.

Building sparse matrices#

eye(m[, n, k, dtype, format])

Creates a sparse matrix with ones on diagonal.

identity(n[, dtype, format])

Creates an identity matrix in sparse format.

diags(diagonals[, offsets, shape, format, dtype])

Construct a sparse matrix from diagonals.

spdiags(data, diags, m, n[, format])

Creates a sparse matrix from diagonals.

bmat(blocks[, format, dtype])

Builds a sparse array/matrix from sparse sub-blocks

rand(m, n[, density, format, dtype, ...])

Generates a random sparse matrix.

random(m, n[, density, format, dtype, ...])

Generates a random sparse matrix.

Combining and manipulating#

As in SciPy, these preserve the input type: the result is a sparse array if any input is a sparse array, and a sparse matrix otherwise. (The *_array builders listed above always return sparse arrays.) matrix_transpose, permute_dims, and swapaxes are 2-D only in CuPy.

kron(A, B[, format])

Kronecker product of sparse arrays/matrices A and B.

kronsum(A, B[, format])

Kronecker sum of sparse arrays/matrices A and B.

hstack(blocks[, format, dtype])

Stacks sparse arrays/matrices horizontally (column wise).

vstack(blocks[, format, dtype])

Stacks sparse arrays/matrices vertically (row wise).

block_diag(mats[, format, dtype])

Build a block-diagonal sparse object from a sequence of blocks.

tril(A[, k, format])

Return the lower triangular portion of a sparse object.

triu(A[, k, format])

Return the upper triangular portion of a sparse object.

matrix_transpose(A)

Transpose the last two axes of a sparse object.

permute_dims(A[, axes, copy])

Permute the axes of a sparse object.

swapaxes(A, axis1, axis2)

Interchange two axes of a sparse object.

Sparse tools#

find(A)

Return the indices and values of nonzero elements of a sparse object.

get_index_dtype([arrays, maxval, check_contents])

Based on input (integer) arrays a, determines a suitable index data type that can hold the data in the arrays.

safely_cast_index_arrays(A[, idx_dtype, msg])

Safely cast sparse array indices to idx_dtype.

Identifying sparse arrays and matrices#

As in SciPy, issparse accepts both sparse arrays and sparse matrices, while isspmatrix and the per-format isspmatrix_* checks are true only for sparse matrices. Use isinstance(x, csr_array) and friends to test for a sparse array of a given format.

issparse(x)

Checks if a given matrix is a sparse matrix or array.

isspmatrix(x)

Checks if a given matrix is a sparse matrix (not array).

isspmatrix_csc(x)

Checks if a given matrix is of CSC format.

isspmatrix_csr(x)

Checks if a given matrix is of CSR format.

isspmatrix_coo(x)

Checks if a given matrix is of COO format.

isspmatrix_dia(x)

Checks if a given matrix is of DIA format.

Submodules#

csgraph

linalg

Exceptions#