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).