legate_sparse.csr_array

class legate_sparse.csr_array(self, arg, shape=None, dtype=None, copy=False)

Compressed Sparse Row array.

This can be instantiated in several ways:

csr_array(D)

where D is a 2-D ndarray or cupynumeric.ndarray

csr_array(S)

with another sparse array or matrix S (equivalent to S.tocsr())

csr_array((M, N), [dtype])

to construct an empty array with shape (M, N) dtype is optional, defaulting to dtype=’d’.

csr_array((data, (row_ind, col_ind)), [shape=(M, N)])

where data, row_ind and col_ind satisfy the relationship a[row_ind[k], col_ind[k]] = data[k].

csr_array((data, indices, indptr), [shape=(M, N)])

is the standard CSR representation where the column indices for row i are stored in indices[indptr[i]:indptr[i+1]] and their corresponding values are stored in data[indptr[i]:indptr[i+1]]. If the shape parameter is not supplied, the array dimensions are inferred from the index arrays.

dtype

Data type of the array

Type:

dtype

shape

Shape of the array

Type:

2-tuple

ndim

Number of dimensions (this is always 2)

Type:

int

nnz

Number of stored values, including explicit zeros

Type:

int

data

CSR format data array of the array

Type:

cupynumeric.ndarray

indices

CSR format index array of the array

Type:

cupynumeric.ndarray

indptr

CSR format index pointer array of the array

Type:

cupynumeric.ndarray

has_sorted_indices

Whether the indices are sorted

Type:

bool

has_canonical_format

Whether the matrix is in canonical format

Type:

bool

T

Transpose of the matrix

Type:

csr_array

Notes

Sparse arrays can be used in arithmetic operations: they support addition, subtraction, multiplication, division, and matrix power.

Advantages of the CSR format:

• fast matrix vector products

Disadvantages of the CSR format:

• changes to the sparsity structure are expensive (consider LIL or DOK)

Canonical Format:

• Within each row, indices are sorted by column.

• There are no duplicate entries.

Differences from SciPy:

• Uses cupynumeric arrays instead of numpy arrays

• GPU acceleration via cuSPARSE when available

• Limited to supported datatypes on GPU: float32, float64, complex64, complex128

• Some operations may create implicit copies due to transformed arrays

• Element-wise operations with scalars only operate on existing non-zero elements

• Indexing with boolean masks only updates existing non-zero elements

Examples

>>> import cupynumeric as np
>>> from legate_sparse import csr_array
>>> csr_array((3, 4), dtype=np.int8).todense()
array([[0, 0, 0, 0],
       [0, 0, 0, 0],
       [0, 0, 0, 0]], dtype=int8)

>>> row = np.array([0, 0, 1, 2, 2, 2])
>>> col = np.array([0, 2, 2, 0, 1, 2])
>>> data = np.array([1, 2, 3, 4, 5, 6])
>>> csr_array((data, (row, col)), shape=(3, 3)).todense()
array([[1, 0, 2],
       [0, 0, 3],
       [4, 5, 6]])

>>> indptr = np.array([0, 2, 3, 6])
>>> indices = np.array([0, 2, 2, 0, 1, 2])
>>> data = np.array([1, 2, 3, 4, 5, 6])
>>> csr_array((data, indices, indptr), shape=(3, 3)).todense()
array([[1, 0, 2],
       [0, 0, 3],
       [4, 5, 6]])

__init__(arg, shape=None, dtype=None, copy=False)

Initialize a CSR array.

Parameters:

• arg (array_like, tuple, or csr_array) – The input data. Can be: - A 2-D dense array (numpy.ndarray or cupynumeric.ndarray) - A sparse array/matrix to convert to CSR format - A tuple (M, N) for an empty array of shape (M, N) - A tuple (data, (row_ind, col_ind)) for COO format data - A tuple (data, indices, indptr) for CSR format data

• shape (tuple, optional) – Shape of the array (M, N). Required if not inferrable from input.

• dtype (dtype, optional) – Data type of the array. If None, inferred from input data. Defaults to float64 if not specified.

• copy (bool, optional) – Whether to copy the input data. Default is False.

Raises:

• NotImplementedError – If the input type is not supported for conversion to CSR.

• AssertionError – If shape cannot be inferred and is not provided.

• ValueError – If input data is inconsistent or invalid.

Notes

When converting from dense arrays, the implementation uses a two-pass algorithm that first counts non-zeros per row, then fills them in. This may not scale well on distributed systems due to alignment constraints.

When converting from COO format, the data is automatically sorted by rows and then by columns to ensure canonical format.

Methods

__init__(arg[, shape, dtype, copy])	Initialize a CSR array.
arcsin()	Element-wise arcsin.
arcsinh()	Element-wise arcsinh.
arctan()	Element-wise arctan.
arctanh()	Element-wise arctanh.
asformat(format[, copy])	Convert this matrix to a specified format.
astype(dtype[, casting, copy])
ceil()	Element-wise ceil.
conj([copy])	Element-wise complex conjugate.
copy()	Returns a copy of this matrix.
deg2rad()	Element-wise deg2rad.
diagonal([k])	Return the k-th diagonal of the matrix.
dot(other[, out])	Ordinary dot product.
expm1()	Element-wise expm1.
floor()	Element-wise floor.
get_data()	Get the data array of the CSR matrix.
get_indices()	Get the column indices array of the CSR matrix.
get_indptr()	Get the index pointer array of the CSR matrix.
has_canonical_format()	Determine whether the matrix is in canonical format.
has_sorted_indices()	Determine whether the matrix has sorted indices.
log1p()	Element-wise log1p.
make_with_same_nnz_structure(mat, arg[, ...])	Create a new matrix with the same non-zero structure as mat.
multiply(other)	Point-wise multiplication by another matrix, vector, or scalar.
nnz_to_pos(q_nnz)	Convert non-zero counts to position arrays for this instance.
nnz_to_pos_cls(q_nnz)	Convert non-zero counts to position arrays.
nonzero()	Return the indices of the non-zero elements.
rad2deg()	Element-wise rad2deg.
rint()	Element-wise rint.
set_data(data)	Set the data array of the CSR matrix.
set_indices(indices)	Set the column indices array of the CSR matrix.
sign()	Element-wise sign.
sin()	Element-wise sin.
sinh()	Element-wise sinh.
sqrt()	Element-wise sqrt.
sum([axis, dtype, out])	Sum the matrix elements over a given axis.
tan()	Element-wise tan.
tanh()	Element-wise tanh.
tocsr([copy])	Convert this matrix to a CSR matrix.
todense([order, out])	Return a dense matrix representation of this matrix.
transpose([axes, copy])	Reverses the dimensions of the sparse matrix.
trunc()	Element-wise trunc.

Attributes

T	Transpose of the matrix
data	CSR format data array of the matrix
dim	Number of dimensions (always 2 for CSR arrays).
dtype	Data type of the array.
indices	CSR format index array of the matrix
indptr	CSR format index pointer array of the matrix
nnz	Number of stored values, including explicit zeros.