dgl.sparse_v0.rst 4.21 KB
Newer Older
1
2
.. _apibackend:

3
dgl.sparse
4
5
=================================

6
`dgl.sparse` is a library for sparse operators that are commonly used in GNN models.
7
8
9
10
11
12

.. 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
-------------------------
13
.. currentmodule:: dgl.sparse
14

Israt Nisa's avatar
Israt Nisa committed
15
16
.. class:: SparseMatrix

17
    Class for creating a sparse matrix representation
Israt Nisa's avatar
Israt Nisa committed
18
19
20

    There are a few ways to create a sparse matrix:

21
22
23
    * In COO format using row and col indices, use :func:`from_coo`.
    * In CSR format using row pointers and col indices, use :func:`from_csr`.
    * In CSC format using col pointers and row indices, use :func:`from_csc`.
Israt Nisa's avatar
Israt Nisa committed
24

25
    For example, one can create COO matrices as follows:
Israt Nisa's avatar
Israt Nisa committed
26

27
    Case1: Sparse matrix with row and column indices without values
Israt Nisa's avatar
Israt Nisa committed
28

29
30
        >>> row = torch.tensor([1, 1, 2])
        >>> col = torch.tensor([2, 4, 3])
31
        >>> A = from_coo(row, col)
Israt Nisa's avatar
Israt Nisa committed
32
33
34
35
36
37
        >>> A
        SparseMatrix(indices=tensor([[1, 1, 2],
                                     [2, 4, 3]]),
                     values=tensor([1., 1., 1.]),
                     shape=(3, 5), nnz=3)

38
    Case2: Sparse matrix with scalar/vector values
Israt Nisa's avatar
Israt Nisa committed
39

40
        >>> # vector values
Israt Nisa's avatar
Israt Nisa committed
41
        >>> val = torch.tensor([[1, 1], [2, 2], [3, 3]])
42
        >>> A = from_coo(row, col, val)
Israt Nisa's avatar
Israt Nisa committed
43
44
45
46
47
48
49
        SparseMatrix(indices=tensor([[1, 1, 2],
                                     [2, 4, 3]]),
                     values=tensor([[1, 1],
                                    [2, 2],
                                    [3, 3]]),
                     shape=(3, 5), nnz=3)

50
    Similarly, one can create a CSR matrix as follows:
Israt Nisa's avatar
Israt Nisa committed
51
52
53
54

        >>> 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]])
55
        >>> A = from_csr(indptr, indices, val)
Israt Nisa's avatar
Israt Nisa committed
56
57
        >>> A
        SparseMatrix(indices=tensor([[0, 1, 2, 2, 2],
58
59
60
61
62
63
64
                                     [1, 2, 0, 1, 2]]),
                     values=tensor([[1, 1],
                                    [2, 2],
                                    [3, 3],
                                    [4, 4],
                                    [5, 5]]),
                     shape=(3, 3), nnz=5)
Israt Nisa's avatar
Israt Nisa committed
65

66
67
Creators
````````
Israt Nisa's avatar
Israt Nisa committed
68
69

.. autosummary::
70
71
    :toctree: ../../generated/

72
73
74
    from_coo
    from_csr
    from_csc
75
76
77
78
79
80
81
    val_like

Attributes and methods
``````````````````````

.. autosummary::
    :toctree: ../../generated/
Israt Nisa's avatar
Israt Nisa committed
82
83
84
85
86

    SparseMatrix.shape
    SparseMatrix.nnz
    SparseMatrix.dtype
    SparseMatrix.device
87
88
    SparseMatrix.val
    SparseMatrix.__repr__
Israt Nisa's avatar
Israt Nisa committed
89
90
91
92
93
94
    SparseMatrix.row
    SparseMatrix.col
    SparseMatrix.indices
    SparseMatrix.coo
    SparseMatrix.csr
    SparseMatrix.csc
95
96
    SparseMatrix.coalesce
    SparseMatrix.has_duplicate
Israt Nisa's avatar
Israt Nisa committed
97
98
99
    SparseMatrix.dense
    SparseMatrix.t
    SparseMatrix.T
100
101
102
103
104
105
106
    SparseMatrix.to
    SparseMatrix.cuda
    SparseMatrix.cpu
    SparseMatrix.float
    SparseMatrix.double
    SparseMatrix.int
    SparseMatrix.long
Israt Nisa's avatar
Israt Nisa committed
107
108
109
110
111
112
    SparseMatrix.transpose
    SparseMatrix.reduce
    SparseMatrix.sum
    SparseMatrix.smax
    SparseMatrix.smin
    SparseMatrix.smean
113
    SparseMatrix.neg
Israt Nisa's avatar
Israt Nisa committed
114
115
    SparseMatrix.softmax
    SparseMatrix.__matmul__
116
117
118

Diagonal matrix class
-------------------------
119
.. currentmodule:: dgl.sparse
120

121
.. class:: DiagMatrix
Israt Nisa's avatar
Israt Nisa committed
122

123
124
Creators
````````
Israt Nisa's avatar
Israt Nisa committed
125
126

.. autosummary::
127
128
129
130
131
132
133
134
135
136
    :toctree: ../../generated/

    diag
    identity

Attributes and methods
``````````````````````

.. autosummary::
    :toctree: ../../generated/
Israt Nisa's avatar
Israt Nisa committed
137
138
139
140
141

    DiagMatrix.shape
    DiagMatrix.nnz
    DiagMatrix.dtype
    DiagMatrix.device
142
143
    DiagMatrix.val
    DiagMatrix.__repr__
Israt Nisa's avatar
Israt Nisa committed
144
    DiagMatrix.as_sparse
145
    DiagMatrix.dense
Israt Nisa's avatar
Israt Nisa committed
146
147
148
    DiagMatrix.t
    DiagMatrix.T
    DiagMatrix.transpose
149
150
151
152
153
154
155
    DiagMatrix.to
    DiagMatrix.cuda
    DiagMatrix.cpu
    DiagMatrix.float
    DiagMatrix.double
    DiagMatrix.int
    DiagMatrix.long
156
    DiagMatrix.neg
Israt Nisa's avatar
Israt Nisa committed
157
158
    DiagMatrix.inv
    DiagMatrix.__matmul__
159

160
161
Operators
---------
162
.. currentmodule:: dgl.sparse
163
164
165
166

.. autosummary::
    :toctree: ../../generated/

167
168
169
170
171
172
173
174
175
176
    sp_add
    sp_mul
    sp_power
    diag_add
    diag_sub
    diag_mul
    diag_div
    diag_power
    add
    power
177
178
    spmm
    bspmm
179
180
    spspmm
    mm
181
    sddmm
182
183
    bsddmm
    softmax