# dgl.mock_sparse¶

dgl_sparse is a library for sparse operators that are commonly used in GNN models.

Warning

This is an experimental package. The sparse operators provided in this library do not guarantee the same performance as their message-passing api counterparts.

## Sparse matrix class¶

class dgl.mock_sparse.SparseMatrix[source]

Class for creating a sparse matrix representation. The row and column indices of the sparse matrix can be the source (row) and destination (column) indices of a homogeneous or heterogeneous graph.

There are a few ways to create a sparse matrix:

For example, we can create COO matrix as follows:

Case1: Sparse matrix with row and column indices without values.

>>> src = torch.tensor([1, 1, 2])
>>> dst = torch.tensor([2, 4, 3])
>>> A = create_from_coo(src, dst)
>>> A
SparseMatrix(indices=tensor([[1, 1, 2],
[2, 4, 3]]),
values=tensor([1., 1., 1.]),
shape=(3, 5), nnz=3)


Case2: Sparse matrix with scalar/vector values. Following example is with vector data.

>>> val = torch.tensor([[1, 1], [2, 2], [3, 3]])
>>> A = create_from_coo(src, dst, val)
SparseMatrix(indices=tensor([[1, 1, 2],
[2, 4, 3]]),
values=tensor([[1, 1],
[2, 2],
[3, 3]]),
shape=(3, 5), nnz=3)


Similarly, we can create CSR matrix as follows:

>>> indptr = torch.tensor([0, 1, 2, 5])
>>> indices = torch.tensor([1, 2, 0, 1, 2])
>>> val = torch.tensor([[1, 1], [2, 2], [3, 3], [4, 4], [5, 5]])
>>> A = create_from_csr(indptr, indices, val)
>>> A
SparseMatrix(indices=tensor([[0, 1, 2, 2, 2],
[1, 2, 0, 1, 2]]),
values=tensor([[1, 1],
[2, 2],
[3, 3],
[4, 4],
[5, 5]]),
shape=(3, 3), nnz=5)


## Sparse matrix class attributes¶

 SparseMatrix.shape Shape of the sparse matrix. SparseMatrix.nnz The number of nonzero elements of the sparse matrix. SparseMatrix.dtype Data type of the values of the sparse matrix. SparseMatrix.device Device of the sparse matrix. SparseMatrix.row Get the row indices of the nonzero elements. SparseMatrix.col Get the column indices of the nonzero elements. SparseMatrix.val Get the values of the nonzero elements. __call__ SparseMatrix.indices(fmt[, return_shuffle]) Get the indices of the nonzero elements. SparseMatrix.coo() Get the coordinate (COO) representation of the sparse matrix. SparseMatrix.csr() Get the CSR (Compressed Sparse Row) representation of the sparse matrix. SparseMatrix.csc() Get the CSC (Compressed Sparse Column) representation of the sparse matrix. SparseMatrix.dense() Get the dense representation of the sparse matrix. SparseMatrix.t() Alias of transpose() SparseMatrix.T Alias of transpose() SparseMatrix.transpose() Return the transpose of this sparse matrix. SparseMatrix.reduce([dim, rtype]) Compute the reduction of non-zero values in sparse matrix A along the given dimension dim. SparseMatrix.sum([dim]) Compute the sum of non-zero values in sparse matrix A along the given dimension dim. SparseMatrix.smax([dim]) Compute the maximum of non-zero values in sparse matrix A along the given dimension dim. SparseMatrix.smin([dim]) Compute the minimum of non-zero values in sparse matrix A along the given dimension dim. SparseMatrix.smean([dim]) Compute the mean of non-zero values in sparse matrix A along the given dimension dim. SparseMatrix.__neg__() Return a new sparse matrix with negative elements. SparseMatrix.inv() Compute the inverse. SparseMatrix.softmax() Apply row-wise softmax to the nonzero entries of the sparse matrix. SparseMatrix.__matmul__(A2) Internal function for multiplying a sparse matrix by a dense/sparse/diagonal matrix
 create_from_coo(row, col[, val, shape]) Create a sparse matrix from row and column coordinates. create_from_csr(indptr, indices[, val, shape]) Create a sparse matrix from CSR indices. create_from_csc(indptr, indices[, val, shape]) Create a sparse matrix from CSC indices.

## Diagonal matrix class¶

class dgl.mock_sparse.DiagMatrix(val: torch.Tensor, shape: Optional[Tuple[int, int]] = None)[source]

Diagonal Matrix Class

Parameters
• val (torch.Tensor) – Diagonal of the matrix. It can take shape (N) or (N, D).

• shape (tuple[int, int], optional) – If not specified, it will be inferred from val, i.e., (N, N). Otherwise, len(val) must be equal to min(shape).

val

Diagonal of the matrix.

Type

torch.Tensor

shape

Shape of the matrix.

Type

tuple[int, int]

## Diagonal matrix class attributes¶

 DiagMatrix.val DiagMatrix.shape DiagMatrix.__call__(x) Create a new diagonal matrix with the same shape as self but different values. DiagMatrix.nnz Return the number of non-zero values in the matrix DiagMatrix.dtype Return the data type of the matrix DiagMatrix.device Return the device of the matrix DiagMatrix.as_sparse() Convert the diagonal matrix into a sparse matrix object DiagMatrix.t() Alias of transpose() DiagMatrix.T Alias of transpose() DiagMatrix.transpose() Return the transpose of the matrix. DiagMatrix.reduce DiagMatrix.sum DiagMatrix.smax DiagMatrix.smin DiagMatrix.smean DiagMatrix.__neg__() Return a new diagonal matrix with negative elements. DiagMatrix.inv() Compute the inverse. DiagMatrix.softmax() Apply row-wise softmax to the nonzero entries of the diagonal matrix. DiagMatrix.__matmul__(A2) Multiply a diagonal matrix by a dense/sparse/diagonal matrix
 diag(val[, shape]) Create a diagonal matrix based on the diagonal values identity(shape[, d, dtype, device]) Create a diagonal matrix with ones on the diagonal and zeros elsewhere

## Operators¶

 spmm(A, X) Multiply a sparse matrix by a dense matrix spspmm(A1, A2) Multiply a sparse matrix by a sparse matrix bspmm(A, X) Batched multiplication of a sparse matrix by a dense matrix, with the last dimension being the batch dimension bspspmm(A1, A2) Batched multiplication of a sparse matrix by a sparse matrix, with the last dimension being the batch dimension sddmm(A, mat1, mat2) Sampled-Dense-Dense Matrix Multiplication (SDDMM).