chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,226 @@
|
||||
.. _apigraph:
|
||||
|
||||
dgl.DGLGraph
|
||||
=====================================================
|
||||
|
||||
.. currentmodule:: dgl
|
||||
.. class:: DGLGraph
|
||||
|
||||
Class for storing graph structure and node/edge feature data.
|
||||
|
||||
There are a few ways to create a DGLGraph:
|
||||
|
||||
* To create a homogeneous graph from Tensor data, use :func:`dgl.graph`.
|
||||
* To create a heterogeneous graph from Tensor data, use :func:`dgl.heterograph`.
|
||||
* To create a graph from other data sources, use ``dgl.*`` create ops. See
|
||||
:ref:`api-graph-create-ops`.
|
||||
|
||||
Read the user guide chapter :ref:`guide-graph` for an in-depth explanation about its
|
||||
usage.
|
||||
|
||||
Querying metagraph structure
|
||||
----------------------------
|
||||
|
||||
Methods for getting information about the node and edge types. They are typically useful
|
||||
when the graph is heterogeneous.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.ntypes
|
||||
DGLGraph.etypes
|
||||
DGLGraph.srctypes
|
||||
DGLGraph.dsttypes
|
||||
DGLGraph.canonical_etypes
|
||||
DGLGraph.metagraph
|
||||
DGLGraph.to_canonical_etype
|
||||
|
||||
.. _apigraph-querying-graph-structure:
|
||||
|
||||
Querying graph structure
|
||||
------------------------
|
||||
|
||||
Methods for getting information about the graph structure such as capacity, connectivity,
|
||||
neighborhood, etc.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.num_nodes
|
||||
DGLGraph.number_of_nodes
|
||||
DGLGraph.num_edges
|
||||
DGLGraph.number_of_edges
|
||||
DGLGraph.num_src_nodes
|
||||
DGLGraph.number_of_src_nodes
|
||||
DGLGraph.num_dst_nodes
|
||||
DGLGraph.number_of_dst_nodes
|
||||
DGLGraph.is_unibipartite
|
||||
DGLGraph.is_multigraph
|
||||
DGLGraph.is_homogeneous
|
||||
DGLGraph.has_nodes
|
||||
DGLGraph.has_edges_between
|
||||
DGLGraph.predecessors
|
||||
DGLGraph.successors
|
||||
DGLGraph.edge_ids
|
||||
DGLGraph.find_edges
|
||||
DGLGraph.in_edges
|
||||
DGLGraph.out_edges
|
||||
DGLGraph.in_degrees
|
||||
DGLGraph.out_degrees
|
||||
|
||||
Querying and manipulating sparse format
|
||||
---------------------------------------
|
||||
|
||||
Methods for getting or manipulating the internal storage formats of a ``DGLGraph``.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.formats
|
||||
DGLGraph.create_formats_
|
||||
|
||||
Querying and manipulating node/edge ID type
|
||||
-----------------------------------------
|
||||
|
||||
Methods for getting or manipulating the data type for storing structure-related
|
||||
data such as node and edge IDs.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.idtype
|
||||
DGLGraph.long
|
||||
DGLGraph.int
|
||||
|
||||
Using Node/edge features
|
||||
------------------------
|
||||
|
||||
Methods for getting or setting the data type for storing structure-related
|
||||
data such as node and edge IDs.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.nodes
|
||||
DGLGraph.ndata
|
||||
DGLGraph.edges
|
||||
DGLGraph.edata
|
||||
DGLGraph.node_attr_schemes
|
||||
DGLGraph.edge_attr_schemes
|
||||
DGLGraph.srcnodes
|
||||
DGLGraph.dstnodes
|
||||
DGLGraph.srcdata
|
||||
DGLGraph.dstdata
|
||||
|
||||
Transforming graph
|
||||
------------------
|
||||
|
||||
Methods for generating a new graph by transforming the current ones. Most of them
|
||||
are alias of the :ref:`api-subgraph-extraction` and :ref:`api-transform`
|
||||
under the ``dgl`` namespace.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.subgraph
|
||||
DGLGraph.edge_subgraph
|
||||
DGLGraph.node_type_subgraph
|
||||
DGLGraph.edge_type_subgraph
|
||||
DGLGraph.__getitem__
|
||||
DGLGraph.line_graph
|
||||
DGLGraph.reverse
|
||||
DGLGraph.add_self_loop
|
||||
DGLGraph.remove_self_loop
|
||||
DGLGraph.to_simple
|
||||
DGLGraph.to_cugraph
|
||||
DGLGraph.reorder_graph
|
||||
|
||||
Adjacency and incidence matrix
|
||||
---------------------------------
|
||||
|
||||
Methods for getting the adjacency and the incidence matrix of the graph.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.adj
|
||||
DGLGraph.adjacency_matrix
|
||||
DGLGraph.adj_tensors
|
||||
DGLGraph.adj_external
|
||||
DGLGraph.inc
|
||||
DGLGraph.incidence_matrix
|
||||
|
||||
Computing with DGLGraph
|
||||
-----------------------------
|
||||
|
||||
Methods for performing message passing, applying functions on node/edge features, etc.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.apply_nodes
|
||||
DGLGraph.apply_edges
|
||||
DGLGraph.send_and_recv
|
||||
DGLGraph.pull
|
||||
DGLGraph.push
|
||||
DGLGraph.update_all
|
||||
DGLGraph.multi_update_all
|
||||
DGLGraph.prop_nodes
|
||||
DGLGraph.prop_edges
|
||||
DGLGraph.filter_nodes
|
||||
DGLGraph.filter_edges
|
||||
|
||||
Querying and manipulating batch information
|
||||
----------------------------------------------
|
||||
|
||||
Methods for getting/setting the batching information if the current graph is a batched
|
||||
graph generated from :func:`dgl.batch`. They are also widely used in the
|
||||
:ref:`api-batch`.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.batch_size
|
||||
DGLGraph.batch_num_nodes
|
||||
DGLGraph.batch_num_edges
|
||||
DGLGraph.set_batch_num_nodes
|
||||
DGLGraph.set_batch_num_edges
|
||||
|
||||
|
||||
Mutating topology
|
||||
-----------------
|
||||
|
||||
Methods for mutating the graph structure *in-place*.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.add_nodes
|
||||
DGLGraph.add_edges
|
||||
DGLGraph.remove_nodes
|
||||
DGLGraph.remove_edges
|
||||
|
||||
Device Control
|
||||
--------------
|
||||
|
||||
Methods for getting or changing the device on which the graph is hosted.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.to
|
||||
DGLGraph.device
|
||||
DGLGraph.cpu
|
||||
DGLGraph.pin_memory_
|
||||
DGLGraph.unpin_memory_
|
||||
DGLGraph.is_pinned
|
||||
|
||||
Misc
|
||||
----
|
||||
|
||||
Other utility methods.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
DGLGraph.local_scope
|
||||
@@ -0,0 +1,148 @@
|
||||
.. _apidata:
|
||||
|
||||
dgl.data
|
||||
=========
|
||||
|
||||
.. currentmodule:: dgl.data
|
||||
.. automodule:: dgl.data
|
||||
|
||||
Base Class
|
||||
---------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
DGLDataset
|
||||
CSVDataset
|
||||
|
||||
Node Prediction Datasets
|
||||
---------------------------------------
|
||||
|
||||
Datasets for node classification/regression tasks
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
SSTDataset
|
||||
KarateClubDataset
|
||||
CoraGraphDataset
|
||||
CiteseerGraphDataset
|
||||
PubmedGraphDataset
|
||||
CoraFullDataset
|
||||
AIFBDataset
|
||||
MUTAGDataset
|
||||
BGSDataset
|
||||
AMDataset
|
||||
AmazonCoBuyComputerDataset
|
||||
AmazonCoBuyPhotoDataset
|
||||
CoauthorCSDataset
|
||||
CoauthorPhysicsDataset
|
||||
PPIDataset
|
||||
RedditDataset
|
||||
SBMMixtureDataset
|
||||
FraudDataset
|
||||
FraudYelpDataset
|
||||
FraudAmazonDataset
|
||||
BAShapeDataset
|
||||
BACommunityDataset
|
||||
TreeCycleDataset
|
||||
TreeGridDataset
|
||||
WikiCSDataset
|
||||
FlickrDataset
|
||||
YelpDataset
|
||||
PATTERNDataset
|
||||
CLUSTERDataset
|
||||
ChameleonDataset
|
||||
SquirrelDataset
|
||||
ActorDataset
|
||||
CornellDataset
|
||||
TexasDataset
|
||||
WisconsinDataset
|
||||
RomanEmpireDataset
|
||||
AmazonRatingsDataset
|
||||
MinesweeperDataset
|
||||
TolokersDataset
|
||||
QuestionsDataset
|
||||
MovieLensDataset
|
||||
VOCSuperpixelsDataset
|
||||
COCOSuperpixelsDataset
|
||||
|
||||
|
||||
Edge Prediction Datasets
|
||||
---------------------------------------
|
||||
|
||||
Datasets for edge classification/regression and link prediction
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
FB15k237Dataset
|
||||
FB15kDataset
|
||||
WN18Dataset
|
||||
BitcoinOTCDataset
|
||||
ICEWS18Dataset
|
||||
GDELTDataset
|
||||
|
||||
Graph Prediction Datasets
|
||||
---------------------------------------
|
||||
|
||||
Datasets for graph classification/regression tasks
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
QM7bDataset
|
||||
QM9Dataset
|
||||
QM9EdgeDataset
|
||||
MiniGCDataset
|
||||
TUDataset
|
||||
LegacyTUDataset
|
||||
GINDataset
|
||||
FakeNewsDataset
|
||||
BA2MotifDataset
|
||||
ZINCDataset
|
||||
PeptidesStructuralDataset
|
||||
PeptidesFunctionalDataset
|
||||
MNISTSuperPixelDataset
|
||||
CIFAR10SuperPixelDataset
|
||||
|
||||
Dataset adapters
|
||||
-------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
AsNodePredDataset
|
||||
AsLinkPredDataset
|
||||
AsGraphPredDataset
|
||||
|
||||
Utilities
|
||||
-----------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
utils.get_download_dir
|
||||
utils.download
|
||||
utils.check_sha1
|
||||
utils.extract_archive
|
||||
utils.split_dataset
|
||||
utils.load_labels
|
||||
utils.save_info
|
||||
utils.load_info
|
||||
utils.add_nodepred_split
|
||||
utils.mask_nodes_by_property
|
||||
utils.add_node_property_split
|
||||
utils.Subset
|
||||
@@ -0,0 +1,85 @@
|
||||
.. _api-dataloading:
|
||||
|
||||
dgl.dataloading
|
||||
=================================
|
||||
|
||||
.. currentmodule:: dgl.dataloading
|
||||
|
||||
The ``dgl.dataloading`` package provides two primitives to compose a data pipeline
|
||||
for loading from graph data. ``Sampler`` represents algorithms
|
||||
to generate subgraph samples from the original graph, and ``DataLoader``
|
||||
represents the iterable over these samples.
|
||||
|
||||
DGL provides a number of built-in samplers that subclass :class:`~dgl.dataloading.Sampler`.
|
||||
Creating new samplers follow the same paradigm. Read our user guide chapter
|
||||
:ref:`guide-minibatch` for more examples and explanations.
|
||||
|
||||
The entire package only works for PyTorch backend.
|
||||
|
||||
DataLoaders
|
||||
-----------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
DataLoader
|
||||
GraphDataLoader
|
||||
|
||||
.. _api-dataloading-neighbor-sampling:
|
||||
|
||||
Samplers
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
Sampler
|
||||
NeighborSampler
|
||||
LaborSampler
|
||||
MultiLayerFullNeighborSampler
|
||||
ClusterGCNSampler
|
||||
ShaDowKHopSampler
|
||||
SAINTSampler
|
||||
|
||||
Sampler Transformations
|
||||
-----------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
as_edge_prediction_sampler
|
||||
BlockSampler
|
||||
|
||||
.. _api-dataloading-negative-sampling:
|
||||
|
||||
Negative Samplers for Link Prediction
|
||||
-------------------------------------
|
||||
.. currentmodule:: dgl.dataloading.negative_sampler
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
Uniform
|
||||
PerSourceUniform
|
||||
GlobalUniform
|
||||
|
||||
Utility Class and Functions for Feature Prefetching
|
||||
---------------------------------------------------
|
||||
.. currentmodule:: dgl.dataloading.base
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
set_node_lazy_features
|
||||
set_edge_lazy_features
|
||||
set_src_lazy_features
|
||||
set_dst_lazy_features
|
||||
LazyFeature
|
||||
@@ -0,0 +1,115 @@
|
||||
.. _api-distributed:
|
||||
|
||||
dgl.distributed
|
||||
=================================
|
||||
|
||||
.. currentmodule:: dgl.distributed
|
||||
|
||||
DGL distributed module contains classes and functions to support
|
||||
distributed Graph Neural Network training and inference on a cluster of
|
||||
machines.
|
||||
|
||||
This includes a few submodules:
|
||||
|
||||
* distributed data structures including distributed graph, distributed tensor
|
||||
and distributed embeddings.
|
||||
* distributed sampling.
|
||||
* distributed workload split at runtime.
|
||||
* graph partition.
|
||||
|
||||
|
||||
Initialization
|
||||
---------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
initialize
|
||||
|
||||
Distributed Graph
|
||||
-----------------
|
||||
|
||||
.. autoclass:: DistGraph
|
||||
:members: ndata, edata, idtype, device, ntypes, etypes, number_of_nodes, number_of_edges, node_attr_schemes, edge_attr_schemes, rank, find_edges, get_partition_book, barrier, local_partition, num_nodes, num_edges, get_node_partition_policy, get_edge_partition_policy, get_etype_id, get_ntype_id, nodes, edges, out_degrees, in_degrees
|
||||
|
||||
Distributed Tensor
|
||||
------------------
|
||||
|
||||
.. autoclass:: DistTensor
|
||||
:members: part_policy, shape, dtype, name
|
||||
|
||||
Distributed Node Embedding
|
||||
---------------------
|
||||
|
||||
.. autoclass:: DistEmbedding
|
||||
|
||||
|
||||
Distributed embedding optimizer
|
||||
-------------------------
|
||||
|
||||
.. autoclass:: dgl.distributed.optim.SparseAdagrad
|
||||
:members: step, save, load
|
||||
|
||||
.. autoclass:: dgl.distributed.optim.SparseAdam
|
||||
:members: step, save, load
|
||||
|
||||
Distributed workload split
|
||||
--------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
node_split
|
||||
edge_split
|
||||
|
||||
Distributed Sampling
|
||||
--------------------
|
||||
|
||||
Distributed DataLoader
|
||||
``````````````````````
|
||||
|
||||
.. autoclass:: NodeCollator
|
||||
|
||||
.. autoclass:: EdgeCollator
|
||||
|
||||
.. autoclass:: DistDataLoader
|
||||
|
||||
.. autoclass:: DistNodeDataLoader
|
||||
|
||||
.. autoclass:: DistEdgeDataLoader
|
||||
|
||||
.. _api-distributed-sampling-ops:
|
||||
Distributed Graph Sampling Operators
|
||||
```````````````````````````````````````
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
sample_neighbors
|
||||
sample_etype_neighbors
|
||||
find_edges
|
||||
in_subgraph
|
||||
|
||||
Partition
|
||||
---------
|
||||
|
||||
Graph partition book
|
||||
````````````````````
|
||||
|
||||
.. autoclass:: GraphPartitionBook
|
||||
:members: shared_memory, num_partitions, metadata, nid2partid, eid2partid, partid2nids, partid2eids, nid2localnid, eid2localeid, partid, map_to_per_ntype, map_to_per_etype, map_to_homo_nid, map_to_homo_eid, canonical_etypes
|
||||
|
||||
.. autoclass:: PartitionPolicy
|
||||
:members: policy_str, part_id, partition_book, to_local, to_partid, get_part_size, get_size
|
||||
|
||||
Split and Load Partitions
|
||||
````````````````````````````
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
load_partition
|
||||
load_partition_feats
|
||||
load_partition_book
|
||||
partition_graph
|
||||
dgl_partition_to_graphbolt
|
||||
@@ -0,0 +1,190 @@
|
||||
.. _apifunction:
|
||||
|
||||
.. currentmodule:: dgl.function
|
||||
|
||||
dgl.function
|
||||
==================================
|
||||
|
||||
This subpackage hosts all the **built-in functions** provided by DGL. Built-in functions
|
||||
are DGL's recommended way to express different types of :ref:`guide-message-passing` computation
|
||||
(i.e., via :func:`~dgl.DGLGraph.update_all`) or computing edge-wise features from
|
||||
node-wise features (i.e., via :func:`~dgl.DGLGraph.apply_edges`). Built-in functions
|
||||
describe the node-wise and edge-wise computation in a symbolic way without any
|
||||
actual computation, so DGL can analyze and map them to efficient low-level kernels.
|
||||
Here are some examples:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import dgl
|
||||
import dgl.function as fn
|
||||
import torch as th
|
||||
g = ... # create a DGLGraph
|
||||
g.ndata['h'] = th.randn((g.num_nodes(), 10)) # each node has feature size 10
|
||||
g.edata['w'] = th.randn((g.num_edges(), 1)) # each edge has feature size 1
|
||||
# collect features from source nodes and aggregate them in destination nodes
|
||||
g.update_all(fn.copy_u('h', 'm'), fn.sum('m', 'h_sum'))
|
||||
# multiply source node features with edge weights and aggregate them in destination nodes
|
||||
g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.max('m', 'h_max'))
|
||||
# compute edge embedding by multiplying source and destination node embeddings
|
||||
g.apply_edges(fn.u_mul_v('h', 'h', 'w_new'))
|
||||
|
||||
``fn.copy_u``, ``fn.u_mul_e``, ``fn.u_mul_v`` are built-in message functions, while ``fn.sum``
|
||||
and ``fn.max`` are built-in reduce functions. DGL's convention is to use ``u``, ``v``
|
||||
and ``e`` to represent source nodes, destination nodes, and edges, respectively.
|
||||
For example, ``copy_u`` tells DGL to copy the source node data as the messages;
|
||||
``u_mul_e`` tells DGL to multiply source node features with edge features.
|
||||
|
||||
To define a unary message function (e.g. ``copy_u``), specify one input feature name and one output
|
||||
message name. To define a binary message function (e.g. ``u_mul_e``), specify
|
||||
two input feature names and one output message name. During the computation,
|
||||
the message function will read the data under the given names, perform computation, and return
|
||||
the output using the output name. For example, the above ``fn.u_mul_e('h', 'w', 'm')`` is
|
||||
the same as the following user-defined function:
|
||||
|
||||
.. code:: python
|
||||
|
||||
def udf_u_mul_e(edges):
|
||||
return {'m' : edges.src['h'] * edges.data['w']}
|
||||
|
||||
To define a reduce function, one input message name and one output node feature name
|
||||
need to be specified. For example, the above ``fn.max('m', 'h_max')`` is the same as the
|
||||
following user-defined function:
|
||||
|
||||
.. code:: python
|
||||
|
||||
def udf_max(nodes):
|
||||
return {'h_max' : th.max(nodes.mailbox['m'], 1)[0]}
|
||||
|
||||
All binary message function supports **broadcasting**, a mechanism for extending element-wise
|
||||
operations to tensor inputs with different shapes. DGL generally follows the standard
|
||||
broadcasting semantic by `NumPy <https://docs.scipy.org/doc/numpy/user/basics.broadcasting.html>`_
|
||||
and `PyTorch <https://pytorch.org/docs/stable/notes/broadcasting.html>`_. Below are some
|
||||
examples:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import dgl
|
||||
import dgl.function as fn
|
||||
import torch as th
|
||||
g = ... # create a DGLGraph
|
||||
|
||||
# case 1
|
||||
g.ndata['h'] = th.randn((g.num_nodes(), 10))
|
||||
g.edata['w'] = th.randn((g.num_edges(), 1))
|
||||
# OK, valid broadcasting between feature shapes (10,) and (1,)
|
||||
g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.sum('m', 'h_new'))
|
||||
g.ndata['h_new'] # shape: (g.num_nodes(), 10)
|
||||
|
||||
# case 2
|
||||
g.ndata['h'] = th.randn((g.num_nodes(), 5, 10))
|
||||
g.edata['w'] = th.randn((g.num_edges(), 10))
|
||||
# OK, valid broadcasting between feature shapes (5, 10) and (10,)
|
||||
g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.sum('m', 'h_new'))
|
||||
g.ndata['h_new'] # shape: (g.num_nodes(), 5, 10)
|
||||
|
||||
# case 3
|
||||
g.ndata['h'] = th.randn((g.num_nodes(), 5, 10))
|
||||
g.edata['w'] = th.randn((g.num_edges(), 5))
|
||||
# NOT OK, invalid broadcasting between feature shapes (5, 10) and (5,)
|
||||
# shapes are aligned from right
|
||||
g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.sum('m', 'h_new'))
|
||||
|
||||
# case 3
|
||||
g.ndata['h1'] = th.randn((g.num_nodes(), 1, 10))
|
||||
g.ndata['h2'] = th.randn((g.num_nodes(), 5, 1))
|
||||
# OK, valid broadcasting between feature shapes (1, 10) and (5, 1)
|
||||
g.apply_edges(fn.u_add_v('h1', 'h2', 'x')) # apply_edges also supports broadcasting
|
||||
g.edata['x'] # shape: (g.num_edges(), 5, 10)
|
||||
|
||||
# case 4
|
||||
g.ndata['h1'] = th.randn((g.num_nodes(), 1, 10, 128))
|
||||
g.ndata['h2'] = th.randn((g.num_nodes(), 5, 1, 128))
|
||||
# OK, u_dot_v supports broadcasting but requires the last dimension to match
|
||||
g.apply_edges(fn.u_dot_v('h1', 'h2', 'x'))
|
||||
g.edata['x'] # shape: (g.num_edges(), 5, 10, 1)
|
||||
|
||||
|
||||
.. _api-built-in:
|
||||
|
||||
DGL Built-in Function
|
||||
-------------------------
|
||||
|
||||
Here is a cheatsheet of all the DGL built-in functions.
|
||||
|
||||
+-------------------------+-----------------------------------------------------------------+-----------------------+
|
||||
| Category | Functions | Memo |
|
||||
+=========================+=================================================================+=======================+
|
||||
| Unary message function | ``copy_u`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``copy_e`` | |
|
||||
+-------------------------+-----------------------------------------------------------------+-----------------------+
|
||||
| Binary message function | ``u_add_v``, ``u_sub_v``, ``u_mul_v``, ``u_div_v``, ``u_dot_v`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``u_add_e``, ``u_sub_e``, ``u_mul_e``, ``u_div_e``, ``u_dot_e`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``v_add_u``, ``v_sub_u``, ``v_mul_u``, ``v_div_u``, ``v_dot_u`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``v_add_e``, ``v_sub_e``, ``v_mul_e``, ``v_div_e``, ``v_dot_e`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``e_add_u``, ``e_sub_u``, ``e_mul_u``, ``e_div_u``, ``e_dot_u`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``e_add_v``, ``e_sub_v``, ``e_mul_v``, ``e_div_v``, ``e_dot_v`` | |
|
||||
+-------------------------+-----------------------------------------------------------------+-----------------------+
|
||||
| Reduce function | ``max`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``min`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``sum`` | |
|
||||
| +-----------------------------------------------------------------+-----------------------+
|
||||
| | ``mean`` | |
|
||||
+-------------------------+-----------------------------------------------------------------+-----------------------+
|
||||
|
||||
Message functions
|
||||
-----------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
copy_u
|
||||
copy_e
|
||||
u_add_v
|
||||
u_sub_v
|
||||
u_mul_v
|
||||
u_div_v
|
||||
u_add_e
|
||||
u_sub_e
|
||||
u_mul_e
|
||||
u_div_e
|
||||
v_add_u
|
||||
v_sub_u
|
||||
v_mul_u
|
||||
v_div_u
|
||||
v_add_e
|
||||
v_sub_e
|
||||
v_mul_e
|
||||
v_div_e
|
||||
e_add_u
|
||||
e_sub_u
|
||||
e_mul_u
|
||||
e_div_u
|
||||
e_add_v
|
||||
e_sub_v
|
||||
e_mul_v
|
||||
e_div_v
|
||||
u_dot_v
|
||||
u_dot_e
|
||||
v_dot_e
|
||||
v_dot_u
|
||||
e_dot_u
|
||||
e_dot_v
|
||||
|
||||
Reduce functions
|
||||
----------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
sum
|
||||
max
|
||||
min
|
||||
mean
|
||||
@@ -0,0 +1,26 @@
|
||||
.. _api-geometry:
|
||||
|
||||
dgl.geometry
|
||||
=================================
|
||||
|
||||
.. automodule:: dgl.geometry
|
||||
|
||||
.. _api-geometry-farthest-point-sampler:
|
||||
|
||||
Farthest Point Sampler
|
||||
-----------
|
||||
|
||||
Farthest point sampling is a greedy algorithm that samples from a point cloud
|
||||
data iteratively. It starts from a random single sample of point. In each iteration,
|
||||
it samples from the rest points that is the farthest from the set of sampled points.
|
||||
|
||||
.. autoclass:: farthest_point_sampler
|
||||
|
||||
.. _api-geometry-neighbor-matching:
|
||||
|
||||
Neighbor Matching
|
||||
-----------------------------
|
||||
|
||||
Neighbor matching is an important module in the Graclus clustering algorithm.
|
||||
|
||||
.. autoclass:: neighbor_matching
|
||||
@@ -0,0 +1,204 @@
|
||||
.. _apibackend:
|
||||
|
||||
🆕 dgl.graphbolt
|
||||
=================================
|
||||
|
||||
.. currentmodule:: dgl.graphbolt
|
||||
|
||||
**dgl.graphbolt** is a dataloading framework for GNNs that provides well-defined
|
||||
APIs for each stage of the data pipeline and multiple standard implementations.
|
||||
|
||||
Dataset
|
||||
-------
|
||||
|
||||
A dataset is a collection of graph structure data, feature data and tasks.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
Dataset
|
||||
OnDiskDataset
|
||||
BuiltinDataset
|
||||
LegacyDataset
|
||||
Task
|
||||
|
||||
Graph
|
||||
-----
|
||||
|
||||
A graph is a collection of nodes and edges. It can be a homogeneous graph or a
|
||||
heterogeneous graph.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
SamplingGraph
|
||||
FusedCSCSamplingGraph
|
||||
|
||||
|
||||
Feature and FeatureStore
|
||||
------------------------
|
||||
|
||||
A feature is a collection of data(tensor, array). A feature store is a
|
||||
collection of features.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
Feature
|
||||
FeatureStore
|
||||
BasicFeatureStore
|
||||
TorchBasedFeature
|
||||
TorchBasedFeatureStore
|
||||
DiskBasedFeature
|
||||
CPUCachedFeature
|
||||
GPUCachedFeature
|
||||
|
||||
|
||||
DataLoader
|
||||
----------
|
||||
|
||||
A dataloader is for iterating over a dataset and generate mini-batches.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
DataLoader
|
||||
|
||||
|
||||
ItemSet
|
||||
-------
|
||||
|
||||
An item set is an iterable collection of items.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
ItemSet
|
||||
HeteroItemSet
|
||||
|
||||
|
||||
ItemSampler
|
||||
-----------
|
||||
|
||||
An item sampler is for sampling items from an item set.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
ItemSampler
|
||||
DistributedItemSampler
|
||||
|
||||
|
||||
MiniBatch
|
||||
---------
|
||||
|
||||
A mini-batch is a collection of sampled subgraphs and their corresponding
|
||||
features. It is the basic unit for training a GNN model.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
MiniBatch
|
||||
MiniBatchTransformer
|
||||
|
||||
|
||||
NegativeSampler
|
||||
---------------
|
||||
|
||||
A negative sampler is for sampling negative items from mini-batches.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
NegativeSampler
|
||||
UniformNegativeSampler
|
||||
|
||||
|
||||
SubgraphSampler
|
||||
---------------
|
||||
|
||||
A subgraph sampler is for sampling subgraphs from a graph.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
SubgraphSampler
|
||||
SampledSubgraph
|
||||
NeighborSampler
|
||||
LayerNeighborSampler
|
||||
TemporalNeighborSampler
|
||||
TemporalLayerNeighborSampler
|
||||
SampledSubgraphImpl
|
||||
FusedSampledSubgraphImpl
|
||||
InSubgraphSampler
|
||||
|
||||
|
||||
FeatureFetcher
|
||||
--------------
|
||||
|
||||
A feature fetcher is for fetching features from a feature store.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
FeatureFetcher
|
||||
|
||||
|
||||
CopyTo
|
||||
------
|
||||
|
||||
This datapipe is for copying data to a device.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: graphbolt_classtemplate.rst
|
||||
|
||||
CopyTo
|
||||
|
||||
|
||||
Utilities
|
||||
---------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
|
||||
cpu_cached_feature
|
||||
gpu_cached_feature
|
||||
fused_csc_sampling_graph
|
||||
load_from_shared_memory
|
||||
from_dglgraph
|
||||
etype_str_to_tuple
|
||||
etype_tuple_to_str
|
||||
isin
|
||||
seed
|
||||
index_select
|
||||
expand_indptr
|
||||
indptr_edge_ids
|
||||
add_reverse_edges
|
||||
exclude_seed_edges
|
||||
compact_csc_format
|
||||
unique_and_compact
|
||||
unique_and_compact_csc_formats
|
||||
numpy_save_aligned
|
||||
@@ -0,0 +1,21 @@
|
||||
.. _apimultiprocessing:
|
||||
|
||||
dgl.multiprocessing
|
||||
===================
|
||||
|
||||
This is a minimal wrapper of Python's native :mod:`multiprocessing` module.
|
||||
It modifies the :class:`multiprocessing.Process` class to make forking
|
||||
work with OpenMP in the DGL core library.
|
||||
|
||||
The API usage is exactly the same as the native module, so DGL does not provide
|
||||
additional documentation.
|
||||
|
||||
In addition, if your backend is PyTorch, this module will also be compatible with
|
||||
:mod:`torch.multiprocessing` module.
|
||||
|
||||
.. currentmodule:: dgl.multiprocessing.pytorch
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
call_once_and_share
|
||||
shared_tensor
|
||||
@@ -0,0 +1,316 @@
|
||||
.. _apibackend:
|
||||
|
||||
.. currentmodule:: dgl.ops
|
||||
|
||||
dgl.ops
|
||||
==================================
|
||||
|
||||
Frame-agnostic operators for message passing on graphs.
|
||||
|
||||
GSpMM functions
|
||||
---------------
|
||||
|
||||
Generalized Sparse-Matrix Dense-Matrix Multiplication functions.
|
||||
It *fuses* two steps into one kernel.
|
||||
|
||||
1. Computes messages by add/sub/mul/div source node and edge features,
|
||||
or copy node features to edges.
|
||||
2. Aggregate the messages by sum/max/min/mean as the features on destination nodes.
|
||||
|
||||
Our implementation supports tensors on CPU/GPU in PyTorch/MXNet/Tensorflow
|
||||
as input. All operators are equipped with autograd (computing the input gradients
|
||||
given output gradient) and broadcasting (if the feature shape of operands do not
|
||||
match, we first broadcast them to the same shape, then applies the binary
|
||||
operators). Our broadcast semantics follows NumPy, please see
|
||||
https://docs.scipy.org/doc/numpy/user/basics.broadcasting.html
|
||||
for more details.
|
||||
|
||||
What do we mean by *fuses* is that the messages are not materialized on edges,
|
||||
instead we compute the result on destination nodes directly, thus saving memory
|
||||
cost. The space complexity of GSpMM operators is :math:`O(|N|D)` where :math:`|N|`
|
||||
refers to the number of nodes in the graph, and :math:`D` refers to the feature
|
||||
size (:math:`D=\prod_{i=1}^{N}D_i` if your feature is a multi-dimensional tensor).
|
||||
|
||||
The following is an example showing how GSpMM works (we use PyTorch as the backend
|
||||
here, you can enjoy the same convenience on other frameworks by similar usage):
|
||||
|
||||
>>> import dgl
|
||||
>>> import torch as th
|
||||
>>> import dgl.ops as F
|
||||
>>> g = dgl.graph(([0, 0, 0, 1, 1, 2], [0, 1, 2, 1, 2, 2])) # 3 nodes, 6 edges
|
||||
>>> x = th.ones(3, 2, requires_grad=True)
|
||||
>>> x
|
||||
tensor([[1., 1.],
|
||||
[1., 1.],
|
||||
[1., 1.]], requires_grad=True)
|
||||
>>> y = th.arange(1, 13).float().view(6, 2).requires_grad_()
|
||||
tensor([[ 1., 2.],
|
||||
[ 3., 4.],
|
||||
[ 5., 6.],
|
||||
[ 7., 8.],
|
||||
[ 9., 10.],
|
||||
[11., 12.]], requires_grad=True)
|
||||
>>> out_1 = F.u_mul_e_sum(g, x, y)
|
||||
>>> out_1 # (10, 12) = ((1, 1) * (3, 4)) + ((1, 1) * (7, 8))
|
||||
tensor([[ 1., 2.],
|
||||
[10., 12.],
|
||||
[25., 28.]], grad_fn=<GSpMMBackward>)
|
||||
>>> out_1.sum().backward()
|
||||
>>> x.grad
|
||||
tensor([[12., 15.],
|
||||
[18., 20.],
|
||||
[12., 13.]])
|
||||
>>> y.grad
|
||||
tensor([[1., 1.],
|
||||
[1., 1.],
|
||||
[1., 1.],
|
||||
[1., 1.],
|
||||
[1., 1.],
|
||||
[1., 1.]])
|
||||
>>> out_2 = F.copy_u_sum(g, x)
|
||||
>>> out_2
|
||||
tensor([[1., 1.],
|
||||
[2., 2.],
|
||||
[3., 3.]], grad_fn=<GSpMMBackward>)
|
||||
>>> out_3 = F.u_add_e_max(g, x, y)
|
||||
>>> out_3
|
||||
tensor([[ 2., 3.],
|
||||
[ 8., 9.],
|
||||
[12., 13.]], grad_fn=<GSpMMBackward>)
|
||||
>>> y1 = th.rand(6, 4, 2, requires_grad=True) # test broadcast
|
||||
>>> F.u_mul_e_sum(g, x, y1).shape # (2,), (4, 2) -> (4, 2)
|
||||
torch.Size([3, 4, 2])
|
||||
|
||||
For all operators, the input graph could either be a homogeneous or a bipartite
|
||||
graph.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
gspmm
|
||||
u_add_e_sum
|
||||
u_sub_e_sum
|
||||
u_mul_e_sum
|
||||
u_div_e_sum
|
||||
u_add_e_max
|
||||
u_sub_e_max
|
||||
u_mul_e_max
|
||||
u_div_e_max
|
||||
u_add_e_min
|
||||
u_sub_e_min
|
||||
u_mul_e_min
|
||||
u_div_e_min
|
||||
u_add_e_mean
|
||||
u_sub_e_mean
|
||||
u_mul_e_mean
|
||||
u_div_e_mean
|
||||
copy_u_sum
|
||||
copy_e_sum
|
||||
copy_u_max
|
||||
copy_e_max
|
||||
copy_u_min
|
||||
copy_e_min
|
||||
copy_u_mean
|
||||
copy_e_mean
|
||||
|
||||
GSDDMM functions
|
||||
----------------
|
||||
|
||||
Generalized Sampled Dense-Dense Matrix Multiplication.
|
||||
It computes edge features by add/sub/mul/div/dot features on source/destination
|
||||
nodes or edges.
|
||||
|
||||
Like GSpMM, our implementation supports tensors on CPU/GPU in
|
||||
PyTorch/MXNet/Tensorflow as input. All operators are equipped with autograd and
|
||||
broadcasting.
|
||||
|
||||
The memory cost of GSDDMM is :math:`O(|E|D)` where :math:`|E|` refers to the number
|
||||
of edges in the graph while :math:`D` refers to the feature size.
|
||||
|
||||
Note that we support ``dot`` operator, which semantically is the same as reduce
|
||||
the last dimension by sum to the result of ``mul`` operator. However, the ``dot``
|
||||
is more memory efficient because it *fuses* ``mul`` and sum reduction, which is
|
||||
critical in the cases while the feature size on last dimension is non-trivial
|
||||
(e.g. multi-head attention in Transformer-like models).
|
||||
|
||||
The following is an example showing how GSDDMM works:
|
||||
|
||||
>>> import dgl
|
||||
>>> import torch as th
|
||||
>>> import dgl.ops as F
|
||||
>>> g = dgl.graph(([0, 0, 0, 1, 1, 2], [0, 1, 2, 1, 2, 2])) # 3 nodes, 6 edges
|
||||
>>> x = th.ones(3, 2, requires_grad=True)
|
||||
>>> x
|
||||
tensor([[1., 1.],
|
||||
[1., 1.],
|
||||
[1., 1.]], requires_grad=True)
|
||||
>>> y = th.arange(1, 7).float().view(3, 2).requires_grad_()
|
||||
>>> y
|
||||
tensor([[1., 2.],
|
||||
[3., 4.],
|
||||
[5., 6.]], requires_grad=True)
|
||||
>>> e = th.ones(6, 1, 2, requires_grad=True) * 2
|
||||
tensor([[[2., 2.]],
|
||||
[[2., 2.]],
|
||||
[[2., 2.]],
|
||||
[[2., 2.]],
|
||||
[[2., 2.]],
|
||||
[[2., 2.]]], grad_fn=<MulBackward0>)
|
||||
>>> out1 = F.u_div_v(g, x, y)
|
||||
tensor([[1.0000, 0.5000],
|
||||
[0.3333, 0.2500],
|
||||
[0.2000, 0.1667],
|
||||
[0.3333, 0.2500],
|
||||
[0.2000, 0.1667],
|
||||
[0.2000, 0.1667]], grad_fn=<GSDDMMBackward>)
|
||||
>>> out1.sum().backward()
|
||||
>>> x.grad
|
||||
tensor([[1.5333, 0.9167],
|
||||
[0.5333, 0.4167],
|
||||
[0.2000, 0.1667]])
|
||||
>>> y.grad
|
||||
tensor([[-1.0000, -0.2500],
|
||||
[-0.2222, -0.1250],
|
||||
[-0.1200, -0.0833]])
|
||||
>>> out2 = F.e_sub_v(g, e, y)
|
||||
>>> out2
|
||||
tensor([[[ 1., 0.]],
|
||||
[[-1., -2.]],
|
||||
[[-3., -4.]],
|
||||
[[-1., -2.]],
|
||||
[[-3., -4.]],
|
||||
[[-3., -4.]]], grad_fn=<GSDDMMBackward>)
|
||||
>>> out3 = F.copy_v(g, y)
|
||||
>>> out3
|
||||
tensor([[1., 2.],
|
||||
[3., 4.],
|
||||
[5., 6.],
|
||||
[3., 4.],
|
||||
[5., 6.],
|
||||
[5., 6.]], grad_fn=<GSDDMMBackward>)
|
||||
>>> out4 = F.u_dot_v(g, x, y)
|
||||
>>> out4 # the last dimension was reduced to size 1.
|
||||
tensor([[ 3.],
|
||||
[ 7.],
|
||||
[11.],
|
||||
[ 7.],
|
||||
[11.],
|
||||
[11.]], grad_fn=<GSDDMMBackward>)
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
gsddmm
|
||||
u_add_v
|
||||
u_sub_v
|
||||
u_mul_v
|
||||
u_dot_v
|
||||
u_div_v
|
||||
u_add_e
|
||||
u_sub_e
|
||||
u_mul_e
|
||||
u_dot_e
|
||||
u_div_e
|
||||
e_add_v
|
||||
e_sub_v
|
||||
e_mul_v
|
||||
e_dot_v
|
||||
e_div_v
|
||||
v_add_u
|
||||
v_sub_u
|
||||
v_mul_u
|
||||
v_dot_u
|
||||
v_div_u
|
||||
e_add_u
|
||||
e_sub_u
|
||||
e_mul_u
|
||||
e_dot_u
|
||||
e_div_u
|
||||
v_add_e
|
||||
v_sub_e
|
||||
v_mul_e
|
||||
v_dot_e
|
||||
v_div_e
|
||||
copy_u
|
||||
copy_v
|
||||
|
||||
Like GSpMM, GSDDMM operators support both homogeneous and bipartite graph.
|
||||
|
||||
Segment Reduce Module
|
||||
---------------------
|
||||
|
||||
DGL provide operators to reduce value tensor along the first dimension by segments.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
segment_reduce
|
||||
|
||||
GatherMM and SegmentMM Module
|
||||
-----------------------------
|
||||
|
||||
SegmentMM: DGL provide operators to perform matrix multiplication according to segments.
|
||||
|
||||
GatherMM: DGL provide operators to gather data according to the given indices and perform matrix multiplication.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
gather_mm
|
||||
segment_mm
|
||||
|
||||
Supported Data types
|
||||
--------------------
|
||||
Operators defined in ``dgl.ops`` support floating point data types, i.e. the operands
|
||||
must be ``half`` (``float16``) /``float``/``double`` tensors.
|
||||
The input tensors must have the same data type (if one input tensor has type float16
|
||||
and the other input tensor has data type float32, user must convert one of them to
|
||||
align with the other one).
|
||||
|
||||
``float16`` data type support is disabled by default as it has a minimum GPU
|
||||
compute capacity requirement of ``sm_53`` (Pascal, Volta, Turing and Ampere
|
||||
architectures).
|
||||
|
||||
User can enable float16 for mixed precision training by compiling DGL from source
|
||||
(see :doc:`Mixed Precision Training </guide/mixed_precision>` tutorial for details).
|
||||
|
||||
Relation with Message Passing APIs
|
||||
----------------------------------
|
||||
|
||||
``dgl.update_all`` and ``dgl.apply_edges`` calls with built-in message/reduce functions
|
||||
would be dispatched into function calls of operators defined in ``dgl.ops``:
|
||||
|
||||
>>> import dgl
|
||||
>>> import torch as th
|
||||
>>> import dgl.ops as F
|
||||
>>> import dgl.function as fn
|
||||
>>> g = dgl.rand_graph(100, 1000) # create a DGLGraph with 100 nodes and 1000 edges.
|
||||
>>> x = th.rand(100, 20) # node features.
|
||||
>>> e = th.rand(1000, 20)
|
||||
>>>
|
||||
>>> # dgl.update_all + builtin functions
|
||||
>>> g.srcdata['x'] = x # srcdata is the same as ndata for graphs with one node type.
|
||||
>>> g.edata['e'] = e
|
||||
>>> g.update_all(fn.u_mul_e('x', 'e', 'm'), fn.sum('m', 'y'))
|
||||
>>> y = g.dstdata['y'] # dstdata is the same as ndata for graphs with one node type.
|
||||
>>>
|
||||
>>> # use GSpMM operators defined in dgl.ops directly
|
||||
>>> y = F.u_mul_e_sum(g, x, e)
|
||||
>>>
|
||||
>>> # dgl.apply_edges + builtin functions
|
||||
>>> g.srcdata['x'] = x
|
||||
>>> g.dstdata['y'] = y
|
||||
>>> g.apply_edges(fn.u_dot_v('x', 'y', 'z'))
|
||||
>>> z = g.edata['z']
|
||||
>>>
|
||||
>>> # use GSDDMM operators defined in dgl.ops directly
|
||||
>>> z = F.u_dot_v(g, x, y)
|
||||
|
||||
It up to user to decide whether to use message-passing APIs or GSpMM/GSDDMM operators, and both
|
||||
of them have the same efficiency. Programs written in message-passing APIs look more like DGL-style
|
||||
but in some cases calling GSpMM/GSDDMM operators is more concise.
|
||||
|
||||
Note that on PyTorch all operators defined in ``dgl.ops`` support higher-order gradients, so as
|
||||
message passing APIs because they entirely depend on these operators.
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
.. _apioptim:
|
||||
|
||||
dgl.optim
|
||||
=========
|
||||
|
||||
.. automodule:: dgl.optim
|
||||
|
||||
Node embedding optimizer
|
||||
-------------------------
|
||||
.. currentmodule:: dgl.optim.pytorch
|
||||
|
||||
.. autoclass:: SparseAdagrad
|
||||
.. autoclass:: SparseAdam
|
||||
@@ -0,0 +1,245 @@
|
||||
.. _apidgl:
|
||||
|
||||
dgl
|
||||
=============================
|
||||
|
||||
.. currentmodule:: dgl
|
||||
.. automodule:: dgl
|
||||
|
||||
.. _api-graph-create-ops:
|
||||
|
||||
Graph Create Ops
|
||||
-------------------------
|
||||
|
||||
Operators for constructing :class:`DGLGraph` from raw data formats.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
graph
|
||||
heterograph
|
||||
from_cugraph
|
||||
from_scipy
|
||||
from_networkx
|
||||
bipartite_from_scipy
|
||||
bipartite_from_networkx
|
||||
rand_graph
|
||||
rand_bipartite
|
||||
knn_graph
|
||||
segmented_knn_graph
|
||||
radius_graph
|
||||
create_block
|
||||
block_to_graph
|
||||
merge
|
||||
|
||||
.. _api-subgraph-extraction:
|
||||
|
||||
Subgraph Extraction Ops
|
||||
-------------------------------------
|
||||
|
||||
Operators for extracting and returning subgraphs.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
node_subgraph
|
||||
edge_subgraph
|
||||
node_type_subgraph
|
||||
edge_type_subgraph
|
||||
in_subgraph
|
||||
out_subgraph
|
||||
khop_in_subgraph
|
||||
khop_out_subgraph
|
||||
|
||||
.. _api-transform:
|
||||
|
||||
Graph Transform Ops
|
||||
----------------------------------
|
||||
|
||||
Operators for generating new graphs by manipulating the structure of the existing ones.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
add_edges
|
||||
add_nodes
|
||||
add_reverse_edges
|
||||
add_self_loop
|
||||
adj_product_graph
|
||||
adj_sum_graph
|
||||
compact_graphs
|
||||
khop_adj
|
||||
khop_graph
|
||||
knn_graph
|
||||
laplacian_lambda_max
|
||||
line_graph
|
||||
metapath_reachable_graph
|
||||
metis_partition
|
||||
metis_partition_assignment
|
||||
norm_by_dst
|
||||
partition_graph_with_halo
|
||||
radius_graph
|
||||
remove_edges
|
||||
remove_nodes
|
||||
remove_self_loop
|
||||
reorder_graph
|
||||
reverse
|
||||
segmented_knn_graph
|
||||
sort_csr_by_tag
|
||||
sort_csc_by_tag
|
||||
to_bidirected
|
||||
to_bidirected_stale
|
||||
to_block
|
||||
to_cugraph
|
||||
to_double
|
||||
to_float
|
||||
to_half
|
||||
to_heterogeneous
|
||||
to_homogeneous
|
||||
to_networkx
|
||||
to_simple
|
||||
to_simple_graph
|
||||
|
||||
.. _api-positional-encoding:
|
||||
|
||||
Graph Positional Encoding Ops:
|
||||
-----------------------------------------
|
||||
|
||||
Operators for generating positional encodings of each node.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated
|
||||
|
||||
random_walk_pe
|
||||
lap_pe
|
||||
double_radius_node_labeling
|
||||
shortest_dist
|
||||
svd_pe
|
||||
|
||||
.. _api-partition:
|
||||
|
||||
Graph Partition Utilities
|
||||
-------------------------
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
metis_partition
|
||||
metis_partition_assignment
|
||||
partition_graph_with_halo
|
||||
|
||||
.. _api-batch:
|
||||
|
||||
Batching and Reading Out Ops
|
||||
-------------------------------
|
||||
|
||||
Operators for batching multiple graphs into one for batch processing and
|
||||
operators for computing graph-level representation for both single and batched graphs.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
batch
|
||||
unbatch
|
||||
slice_batch
|
||||
readout_nodes
|
||||
readout_edges
|
||||
sum_nodes
|
||||
sum_edges
|
||||
mean_nodes
|
||||
mean_edges
|
||||
max_nodes
|
||||
max_edges
|
||||
softmax_nodes
|
||||
softmax_edges
|
||||
broadcast_nodes
|
||||
broadcast_edges
|
||||
topk_nodes
|
||||
topk_edges
|
||||
|
||||
Adjacency Related Utilities
|
||||
-------------------------------
|
||||
|
||||
Utilities for computing adjacency matrix and Lapacian matrix.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
khop_adj
|
||||
laplacian_lambda_max
|
||||
|
||||
Graph Traversal & Message Propagation
|
||||
------------------------------------------
|
||||
|
||||
DGL implements graph traversal algorithms implemented as python generators,
|
||||
which returns the visited set of nodes or edges (in ID tensor) at each iteration.
|
||||
The naming convention is ``<algorithm>_[nodes|edges]_generator``.
|
||||
An example usage is as follows.
|
||||
|
||||
.. code:: python
|
||||
|
||||
g = ... # some DGLGraph
|
||||
for nodes in dgl.bfs_nodes_generator(g, 0):
|
||||
do_something(nodes)
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
bfs_nodes_generator
|
||||
bfs_edges_generator
|
||||
topological_nodes_generator
|
||||
dfs_edges_generator
|
||||
dfs_labeled_edges_generator
|
||||
|
||||
DGL provides APIs to perform message passing following graph traversal order. ``prop_nodes_XXX``
|
||||
calls traversal algorithm ``XXX`` and triggers :func:`~DGLGraph.pull()` on the visited node
|
||||
set at each iteration. ``prop_edges_YYY`` applies traversal algorithm ``YYY`` and triggers
|
||||
:func:`~DGLGraph.send_and_recv()` on the visited edge set at each iteration.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
prop_nodes
|
||||
prop_nodes_bfs
|
||||
prop_nodes_topo
|
||||
prop_edges
|
||||
prop_edges_dfs
|
||||
|
||||
Homophily Measures
|
||||
-------------------------
|
||||
|
||||
Utilities for measuring homophily of a graph
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
edge_homophily
|
||||
node_homophily
|
||||
linkx_homophily
|
||||
adjusted_homophily
|
||||
|
||||
Label Informativeness Measures
|
||||
-------------------------
|
||||
|
||||
Utilities for measuring label informativeness of a graph
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
edge_label_informativeness
|
||||
node_label_informativeness
|
||||
|
||||
Utilities
|
||||
-----------------------------------------------
|
||||
|
||||
Other utilities for controlling randomness, saving and loading graphs, setting and getting runtime configurations, functions that applies
|
||||
the same function to every elements in a container, etc.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
seed
|
||||
save_graphs
|
||||
load_graphs
|
||||
apply_each
|
||||
use_libxsmm
|
||||
is_libxsmm_enabled
|
||||
@@ -0,0 +1,36 @@
|
||||
.. _api-sampling:
|
||||
|
||||
dgl.sampling
|
||||
=================================
|
||||
|
||||
.. automodule:: dgl.sampling
|
||||
|
||||
Random walk
|
||||
------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
random_walk
|
||||
node2vec_random_walk
|
||||
pack_traces
|
||||
|
||||
Neighbor sampling
|
||||
---------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
sample_neighbors
|
||||
sample_labors
|
||||
sample_neighbors_biased
|
||||
select_topk
|
||||
PinSAGESampler
|
||||
|
||||
Negative sampling
|
||||
-----------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
global_uniform_negative_sampling
|
||||
@@ -0,0 +1,124 @@
|
||||
.. _apibackend:
|
||||
|
||||
dgl.sparse
|
||||
=================================
|
||||
|
||||
`dgl.sparse` is a library for sparse operators that are commonly used in GNN models.
|
||||
|
||||
Sparse matrix class
|
||||
-------------------------
|
||||
.. currentmodule:: dgl.sparse
|
||||
|
||||
.. class:: SparseMatrix
|
||||
|
||||
A SparseMatrix can be created from Coordinate format indices using the
|
||||
:func:`spmatrix` constructor:
|
||||
|
||||
>>> indices = torch.tensor([[1, 1, 2],
|
||||
>>> [2, 4, 3]])
|
||||
>>> A = dglsp.spmatrix(indices)
|
||||
SparseMatrix(indices=tensor([[1, 1, 2],
|
||||
[2, 4, 3]]),
|
||||
values=tensor([1., 1., 1.]),
|
||||
shape=(3, 5), nnz=3)
|
||||
|
||||
Creation Ops
|
||||
````````
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
spmatrix
|
||||
val_like
|
||||
from_coo
|
||||
from_csr
|
||||
from_csc
|
||||
diag
|
||||
identity
|
||||
|
||||
Attributes and methods
|
||||
``````````````````````
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
SparseMatrix.shape
|
||||
SparseMatrix.nnz
|
||||
SparseMatrix.dtype
|
||||
SparseMatrix.device
|
||||
SparseMatrix.val
|
||||
SparseMatrix.row
|
||||
SparseMatrix.col
|
||||
SparseMatrix.indices
|
||||
SparseMatrix.coo
|
||||
SparseMatrix.csr
|
||||
SparseMatrix.csc
|
||||
SparseMatrix.coalesce
|
||||
SparseMatrix.has_duplicate
|
||||
SparseMatrix.to_dense
|
||||
SparseMatrix.to
|
||||
SparseMatrix.cuda
|
||||
SparseMatrix.cpu
|
||||
SparseMatrix.float
|
||||
SparseMatrix.double
|
||||
SparseMatrix.int
|
||||
SparseMatrix.long
|
||||
SparseMatrix.transpose
|
||||
SparseMatrix.t
|
||||
SparseMatrix.T
|
||||
SparseMatrix.neg
|
||||
SparseMatrix.reduce
|
||||
SparseMatrix.sum
|
||||
SparseMatrix.smax
|
||||
SparseMatrix.smin
|
||||
SparseMatrix.smean
|
||||
SparseMatrix.softmax
|
||||
|
||||
Operators
|
||||
---------
|
||||
.. currentmodule:: dgl.sparse
|
||||
|
||||
Elementwise Operators
|
||||
````````
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
add
|
||||
sub
|
||||
mul
|
||||
div
|
||||
power
|
||||
|
||||
Matrix Multiplication
|
||||
````````
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
matmul
|
||||
spmm
|
||||
bspmm
|
||||
spspmm
|
||||
sddmm
|
||||
bsddmm
|
||||
|
||||
Non-linear activation functions
|
||||
````````
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
softmax
|
||||
|
||||
Broadcast operators
|
||||
````````
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
sp_broadcast_v
|
||||
sp_add_v
|
||||
sp_sub_v
|
||||
sp_mul_v
|
||||
sp_div_v
|
||||
@@ -0,0 +1,19 @@
|
||||
API Reference
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
dgl
|
||||
dgl.data
|
||||
dgl.dataloading
|
||||
dgl.DGLGraph
|
||||
dgl.distributed
|
||||
dgl.function
|
||||
nn-pytorch
|
||||
nn-tensorflow
|
||||
nn-mxnet
|
||||
dgl.ops
|
||||
dgl.sampling
|
||||
udf
|
||||
transforms
|
||||
@@ -0,0 +1,128 @@
|
||||
.. _knn_benchmark:
|
||||
|
||||
Benchmark the performance of KNN algorithms
|
||||
===========================================
|
||||
|
||||
In this doc, we benchmark the performance on multiple K-Nearest Neighbor algorithms implemented by :func:`dgl.knn_graph`.
|
||||
|
||||
Given a dataset of ``N`` samples with ``D`` dimensions, the common use case of KNN algorithms in graph learning is to build a KNN graph by finding the ``K`` nearest neighbors for each of the ``N`` samples among the dataset.
|
||||
|
||||
Empirically, the three parameters, ``N``, ``D``, and ``K``, all have impact on the computation cost. To benchmark the algorithms, we pick a few represensitive datasets to cover most common scenarios:
|
||||
|
||||
* A synthetic dataset with mixed gaussian samples: ``N = 1000``, ``D = 3``.
|
||||
* A point cloud sample from ModelNet: ``N = 10000``, ``D = 3``.
|
||||
* Subsets of MNIST
|
||||
- A small subset: ``N = 1000``, ``D = 784``
|
||||
- A medium subset: ``N = 10000``, ``D = 784``
|
||||
- A large subset: ``N = 50000``, ``D = 784``
|
||||
|
||||
Some notes:
|
||||
|
||||
* ``bruteforce-sharemem`` is an optimized implementation of ``bruteforce`` on GPU.
|
||||
* ``kd-tree`` is currently only implemented on CPU.
|
||||
* ``bruteforce-blas`` conducts matrix multiplication, thus is memory inefficient.
|
||||
* ``nn-descent`` is an approximate algorithm, and we also report the recall rate of its result.
|
||||
|
||||
Results
|
||||
-------
|
||||
|
||||
In this section, we show the runtime and recall rate (where applicable) for the algorithms under various scenarios.
|
||||
|
||||
The experiments are run on an Amazon EC2 P3.2xlarge instance. This instance has 8 vCPUs with 61GB RAM, and one Tesla V100 GPU with 16GB RAM. In terms of the environment, we obtain the numbers with DGL==0.7.0(`64d0f3f <https://github.com/dmlc/dgl/commit/64d0f3f3554911ec06d015f1c9659180796adf9a>`_), PyTorch==1.8.1, CUDA==11.1 on Ubuntu 18.04.5 LTS.
|
||||
|
||||
* **Mixed Gaussian:**
|
||||
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| Model | CPU | GPU |
|
||||
| +------------------+-------------------+------------------+------------------+
|
||||
| | K = 8 | K = 64 | K = 8 | K = 64 |
|
||||
+=====================+==================+===================+==================+==================+
|
||||
| bruteforce-blas | 0.010 | 0.011 | 0.002 | 0.003 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| kd-tree | 0.004 | 0.006 | n/a | n/a |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce | 0.004 | 0.006 | 0.126 | 0.009 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce-sharemem | n/a | n/a | 0.002 | 0.003 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| nn-descent | 0.014 (R: 0.985) | 0.148 (R: 1.000) | 0.016 (R: 0.973) | 0.077 (R: 1.000) |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
|
||||
* **Point Cloud**
|
||||
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| Model | CPU | GPU |
|
||||
| +------------------+-------------------+------------------+------------------+
|
||||
| | K = 8 | K = 64 | K = 8 | K = 64 |
|
||||
+=====================+==================+===================+==================+==================+
|
||||
| bruteforce-blas | 0.359 | 0.432 | 0.010 | 0.010 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| kd-tree | 0.007 | 0.026 | n/a | n/a |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce | 0.074 | 0.167 | 0.008 | 0.039 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce-sharemem | n/a | n/a | 0.004 | 0.017 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| nn-descent | 0.161 (R: 0.977) | 1.345 (R: 0.999) | 0.086 (R: 0.966) | 0.445 (R: 0.999) |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
|
||||
* **Small MNIST**
|
||||
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| Model | CPU | GPU |
|
||||
| +------------------+-------------------+------------------+------------------+
|
||||
| | K = 8 | K = 64 | K = 8 | K = 64 |
|
||||
+=====================+==================+===================+==================+==================+
|
||||
| bruteforce-blas | 0.014 | 0.015 | 0.002 | 0.002 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| kd-tree | 0.179 | 0.182 | n/a | n/a |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce | 0.173 | 0.228 | 0.123 | 0.170 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce-sharemem | n/a | n/a | 0.045 | 0.054 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| nn-descent | 0.060 (R: 0.878) | 1.077 (R: 0.999) | 0.030 (R: 0.952) | 0.457 (R: 0.999) |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
|
||||
* **Medium MNIST**
|
||||
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| Model | CPU | GPU |
|
||||
| +------------------+-------------------+------------------+------------------+
|
||||
| | K = 8 | K = 64 | K = 8 | K = 64 |
|
||||
+=====================+==================+===================+==================+==================+
|
||||
| bruteforce-blas | 0.897 | 0.970 | 0.019 | 0.023 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| kd-tree | 18.902 | 18.928 | n/a | n/a |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce | 14.495 | 17.652 | 2.058 | 2.588 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce-sharemem | n/a | n/a | 2.257 | 2.524 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| nn-descent | 0.804 (R: 0.755) | 14.108 (R: 0.999) | 0.158 (R: 0.900) | 1.794 (R: 0.999) |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
|
||||
* **Large MNIST**
|
||||
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| Model | CPU | GPU |
|
||||
| +------------------+-------------------+------------------+------------------+
|
||||
| | K = 8 | K = 64 | K = 8 | K = 64 |
|
||||
+=====================+==================+===================+==================+==================+
|
||||
| bruteforce-blas | 21.829 | 22.135 | Out of Memory | Out of Memory |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| kd-tree | 542.688 | 573.379 | n/a | n/a |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce | 373.823 | 432.963 | 10.317 | 12.639 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| bruteforce-sharemem | n/a | n/a | 53.133 | 58.419 |
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
| nn-descent | 4.995 (R: 0.658) | 75.487 (R: 0.999) | 1.478 (R: 0.860) | 15.698 (R: 0.999)|
|
||||
+---------------------+------------------+-------------------+------------------+------------------+
|
||||
|
||||
Conclusion
|
||||
----------
|
||||
|
||||
- As long as you have enough memory, ``bruteforce-blas`` is the default algorithm to go with.
|
||||
- Specifically, when ``D`` is small and the data is on CPU, ``kd-tree`` is the best algorithm.
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
.. _apinn-mxnet:
|
||||
|
||||
dgl.nn (MXNet)
|
||||
================
|
||||
|
||||
Conv Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.mxnet.conv.GraphConv
|
||||
~dgl.nn.mxnet.conv.RelGraphConv
|
||||
~dgl.nn.mxnet.conv.TAGConv
|
||||
~dgl.nn.mxnet.conv.GATConv
|
||||
~dgl.nn.mxnet.conv.EdgeConv
|
||||
~dgl.nn.mxnet.conv.SAGEConv
|
||||
~dgl.nn.mxnet.conv.SGConv
|
||||
~dgl.nn.mxnet.conv.APPNPConv
|
||||
~dgl.nn.mxnet.conv.GINConv
|
||||
~dgl.nn.mxnet.conv.GatedGraphConv
|
||||
~dgl.nn.mxnet.conv.GMMConv
|
||||
~dgl.nn.mxnet.conv.ChebConv
|
||||
~dgl.nn.mxnet.conv.AGNNConv
|
||||
~dgl.nn.mxnet.conv.NNConv
|
||||
|
||||
Dense Conv Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.mxnet.conv.DenseGraphConv
|
||||
~dgl.nn.mxnet.conv.DenseSAGEConv
|
||||
~dgl.nn.mxnet.conv.DenseChebConv
|
||||
|
||||
Global Pooling Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.mxnet.glob.SumPooling
|
||||
~dgl.nn.mxnet.glob.AvgPooling
|
||||
~dgl.nn.mxnet.glob.MaxPooling
|
||||
~dgl.nn.mxnet.glob.SortPooling
|
||||
~dgl.nn.mxnet.glob.GlobalAttentionPooling
|
||||
~dgl.nn.mxnet.glob.Set2Set
|
||||
|
||||
Heterogeneous Learning Modules
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.mxnet.HeteroGraphConv
|
||||
|
||||
Utility Modules
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.mxnet.utils.Sequential
|
||||
@@ -0,0 +1,162 @@
|
||||
.. _apinn-pytorch:
|
||||
|
||||
dgl.nn (PyTorch)
|
||||
================
|
||||
|
||||
Conv Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.conv.GraphConv
|
||||
~dgl.nn.pytorch.conv.EdgeWeightNorm
|
||||
~dgl.nn.pytorch.conv.RelGraphConv
|
||||
~dgl.nn.pytorch.conv.TAGConv
|
||||
~dgl.nn.pytorch.conv.GATConv
|
||||
~dgl.nn.pytorch.conv.GATv2Conv
|
||||
~dgl.nn.pytorch.conv.EGATConv
|
||||
~dgl.nn.pytorch.conv.EdgeGATConv
|
||||
~dgl.nn.pytorch.conv.EdgeConv
|
||||
~dgl.nn.pytorch.conv.SAGEConv
|
||||
~dgl.nn.pytorch.conv.SGConv
|
||||
~dgl.nn.pytorch.conv.APPNPConv
|
||||
~dgl.nn.pytorch.conv.GINConv
|
||||
~dgl.nn.pytorch.conv.GINEConv
|
||||
~dgl.nn.pytorch.conv.GatedGraphConv
|
||||
~dgl.nn.pytorch.conv.GatedGCNConv
|
||||
~dgl.nn.pytorch.conv.GMMConv
|
||||
~dgl.nn.pytorch.conv.ChebConv
|
||||
~dgl.nn.pytorch.conv.AGNNConv
|
||||
~dgl.nn.pytorch.conv.NNConv
|
||||
~dgl.nn.pytorch.conv.AtomicConv
|
||||
~dgl.nn.pytorch.conv.CFConv
|
||||
~dgl.nn.pytorch.conv.DotGatConv
|
||||
~dgl.nn.pytorch.conv.TWIRLSConv
|
||||
~dgl.nn.pytorch.conv.TWIRLSUnfoldingAndAttention
|
||||
~dgl.nn.pytorch.conv.GCN2Conv
|
||||
~dgl.nn.pytorch.conv.HGTConv
|
||||
~dgl.nn.pytorch.conv.GroupRevRes
|
||||
~dgl.nn.pytorch.conv.EGNNConv
|
||||
~dgl.nn.pytorch.conv.PNAConv
|
||||
~dgl.nn.pytorch.conv.DGNConv
|
||||
|
||||
CuGraph Conv Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.conv.CuGraphRelGraphConv
|
||||
~dgl.nn.pytorch.conv.CuGraphGATConv
|
||||
~dgl.nn.pytorch.conv.CuGraphSAGEConv
|
||||
|
||||
Dense Conv Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.conv.DenseGraphConv
|
||||
~dgl.nn.pytorch.conv.DenseSAGEConv
|
||||
~dgl.nn.pytorch.conv.DenseChebConv
|
||||
|
||||
Global Pooling Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.glob.SumPooling
|
||||
~dgl.nn.pytorch.glob.AvgPooling
|
||||
~dgl.nn.pytorch.glob.MaxPooling
|
||||
~dgl.nn.pytorch.glob.SortPooling
|
||||
~dgl.nn.pytorch.glob.WeightAndSum
|
||||
~dgl.nn.pytorch.glob.GlobalAttentionPooling
|
||||
~dgl.nn.pytorch.glob.Set2Set
|
||||
~dgl.nn.pytorch.glob.SetTransformerEncoder
|
||||
~dgl.nn.pytorch.glob.SetTransformerDecoder
|
||||
|
||||
Score Modules for Link Prediction and Knowledge Graph Completion
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.link.EdgePredictor
|
||||
~dgl.nn.pytorch.link.TransE
|
||||
~dgl.nn.pytorch.link.TransR
|
||||
|
||||
Heterogeneous Learning Modules
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.HeteroGraphConv
|
||||
~dgl.nn.pytorch.HeteroLinear
|
||||
~dgl.nn.pytorch.HeteroEmbedding
|
||||
~dgl.nn.pytorch.TypedLinear
|
||||
|
||||
Utility Modules
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.utils.Sequential
|
||||
~dgl.nn.pytorch.utils.WeightBasis
|
||||
~dgl.nn.pytorch.factory.KNNGraph
|
||||
~dgl.nn.pytorch.factory.SegmentedKNNGraph
|
||||
~dgl.nn.pytorch.factory.RadiusGraph
|
||||
~dgl.nn.pytorch.utils.JumpingKnowledge
|
||||
~dgl.nn.pytorch.sparse_emb.NodeEmbedding
|
||||
~dgl.nn.pytorch.explain.GNNExplainer
|
||||
~dgl.nn.pytorch.explain.HeteroGNNExplainer
|
||||
~dgl.nn.pytorch.explain.SubgraphX
|
||||
~dgl.nn.pytorch.explain.HeteroSubgraphX
|
||||
~dgl.nn.pytorch.explain.PGExplainer
|
||||
~dgl.nn.pytorch.explain.HeteroPGExplainer
|
||||
~dgl.nn.pytorch.utils.LabelPropagation
|
||||
~dgl.nn.pytorch.utils.LaplacianPosEnc
|
||||
|
||||
Network Embedding Modules
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.DeepWalk
|
||||
~dgl.nn.pytorch.MetaPath2Vec
|
||||
|
||||
Utility Modules for Graph Transformer
|
||||
----------------------------------------
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.pytorch.gt.DegreeEncoder
|
||||
~dgl.nn.pytorch.gt.LapPosEncoder
|
||||
~dgl.nn.pytorch.gt.PathEncoder
|
||||
~dgl.nn.pytorch.gt.SpatialEncoder
|
||||
~dgl.nn.pytorch.gt.SpatialEncoder3d
|
||||
~dgl.nn.pytorch.gt.BiasedMHA
|
||||
~dgl.nn.pytorch.gt.GraphormerLayer
|
||||
~dgl.nn.pytorch.gt.EGTLayer
|
||||
@@ -0,0 +1,45 @@
|
||||
.. _apinn-tensorflow:
|
||||
|
||||
dgl.nn (TensorFlow)
|
||||
================
|
||||
|
||||
Conv Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.tensorflow.conv.GraphConv
|
||||
~dgl.nn.tensorflow.conv.RelGraphConv
|
||||
~dgl.nn.tensorflow.conv.GATConv
|
||||
~dgl.nn.tensorflow.conv.SAGEConv
|
||||
~dgl.nn.tensorflow.conv.ChebConv
|
||||
~dgl.nn.tensorflow.conv.SGConv
|
||||
~dgl.nn.tensorflow.conv.APPNPConv
|
||||
~dgl.nn.tensorflow.conv.GINConv
|
||||
|
||||
Global Pooling Layers
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.tensorflow.glob.SumPooling
|
||||
~dgl.nn.tensorflow.glob.AvgPooling
|
||||
~dgl.nn.tensorflow.glob.MaxPooling
|
||||
~dgl.nn.tensorflow.glob.SortPooling
|
||||
~dgl.nn.tensorflow.glob.GlobalAttentionPooling
|
||||
|
||||
Heterogeneous Learning Modules
|
||||
----------------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
~dgl.nn.tensorflow.glob.HeteroGraphConv
|
||||
@@ -0,0 +1,11 @@
|
||||
.. _apinn-functional:
|
||||
|
||||
dgl.nn.functional
|
||||
=================
|
||||
|
||||
.. automodule:: dgl.nn.functional
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
edge_softmax
|
||||
@@ -0,0 +1,37 @@
|
||||
.. _apitransform-namespace:
|
||||
|
||||
dgl.transforms
|
||||
==============
|
||||
|
||||
.. currentmodule:: dgl.transforms
|
||||
.. automodule:: dgl.transforms
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
:nosignatures:
|
||||
:template: classtemplate.rst
|
||||
|
||||
BaseTransform
|
||||
Compose
|
||||
AddSelfLoop
|
||||
RemoveSelfLoop
|
||||
AddReverse
|
||||
ToSimple
|
||||
LineGraph
|
||||
KHopGraph
|
||||
AddMetaPaths
|
||||
GCNNorm
|
||||
PPR
|
||||
HeatKernel
|
||||
GDC
|
||||
NodeShuffle
|
||||
DropNode
|
||||
DropEdge
|
||||
AddEdge
|
||||
RandomWalkPE
|
||||
LapPE
|
||||
FeatMask
|
||||
RowFeatNormalizer
|
||||
SIGNDiffusion
|
||||
ToLevi
|
||||
SVDPE
|
||||
@@ -0,0 +1,116 @@
|
||||
.. _apiudf:
|
||||
|
||||
User-defined Functions
|
||||
==================================================
|
||||
|
||||
.. currentmodule:: dgl.udf
|
||||
|
||||
User-defined functions (UDFs) allow arbitrary computation in message passing
|
||||
(see :ref:`guide-message-passing`) and edge feature update with
|
||||
:func:`~dgl.DGLGraph.apply_edges`. They bring more flexibility when :ref:`apifunction`
|
||||
cannot realize a desired computation.
|
||||
|
||||
Edge-wise User-defined Function
|
||||
-------------------------------
|
||||
|
||||
One can use an edge-wise user defined function for a message function in message passing or
|
||||
a function to apply in :func:`~dgl.DGLGraph.apply_edges`. It takes a batch of edges as input
|
||||
and returns messages (in message passing) or features (in :func:`~dgl.DGLGraph.apply_edges`)
|
||||
for each edge. The function may combine the features of the edges and their end nodes in
|
||||
computation.
|
||||
|
||||
Formally, it takes the following form
|
||||
|
||||
.. code::
|
||||
|
||||
def edge_udf(edges):
|
||||
"""
|
||||
Parameters
|
||||
----------
|
||||
edges : EdgeBatch
|
||||
A batch of edges.
|
||||
|
||||
Returns
|
||||
-------
|
||||
dict[str, tensor]
|
||||
The messages or edge features generated. It maps a message/feature name to the
|
||||
corresponding messages/features of all edges in the batch. The order of the
|
||||
messages/features is the same as the order of the edges in the input argument.
|
||||
"""
|
||||
|
||||
DGL generates :class:`~dgl.udf.EdgeBatch` instances internally, which expose the following
|
||||
interface for defining ``edge_udf``.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
EdgeBatch.src
|
||||
EdgeBatch.dst
|
||||
EdgeBatch.data
|
||||
EdgeBatch.edges
|
||||
EdgeBatch.batch_size
|
||||
|
||||
Node-wise User-defined Function
|
||||
-------------------------------
|
||||
|
||||
One can use a node-wise user defined function for a reduce function in message passing. It takes
|
||||
a batch of nodes as input and returns the updated features for each node. It may combine the
|
||||
current node features and the messages nodes received. Formally, it takes the following form
|
||||
|
||||
.. code::
|
||||
|
||||
def node_udf(nodes):
|
||||
"""
|
||||
Parameters
|
||||
----------
|
||||
nodes : NodeBatch
|
||||
A batch of nodes.
|
||||
|
||||
Returns
|
||||
-------
|
||||
dict[str, tensor]
|
||||
The updated node features. It maps a feature name to the corresponding features of
|
||||
all nodes in the batch. The order of the nodes is the same as the order of the nodes
|
||||
in the input argument.
|
||||
"""
|
||||
|
||||
DGL generates :class:`~dgl.udf.NodeBatch` instances internally, which expose the following
|
||||
interface for defining ``node_udf``.
|
||||
|
||||
.. autosummary::
|
||||
:toctree: ../../generated/
|
||||
|
||||
NodeBatch.data
|
||||
NodeBatch.mailbox
|
||||
NodeBatch.nodes
|
||||
NodeBatch.batch_size
|
||||
|
||||
Degree Bucketing for Message Passing with User Defined Functions
|
||||
----------------------------------------------------------------
|
||||
|
||||
DGL employs a degree-bucketing mechanism for message passing with UDFs. It groups nodes with
|
||||
a same in-degree and invokes message passing for each group of nodes. As a result, one shall
|
||||
not make any assumptions about the batch size of :class:`~dgl.udf.NodeBatch` instances.
|
||||
|
||||
For a batch of nodes, DGL stacks the incoming messages of each node along the second dimension,
|
||||
ordered by edge ID. An example goes as follows:
|
||||
|
||||
.. code:: python
|
||||
|
||||
>>> import dgl
|
||||
>>> import torch
|
||||
>>> import dgl.function as fn
|
||||
>>> g = dgl.graph(([1, 3, 5, 0, 4, 2, 3, 3, 4, 5], [1, 1, 0, 0, 1, 2, 2, 0, 3, 3]))
|
||||
>>> g.edata['eid'] = torch.arange(10)
|
||||
>>> def reducer(nodes):
|
||||
... print(nodes.mailbox['eid'])
|
||||
... return {'n': nodes.mailbox['eid'].sum(1)}
|
||||
>>> g.update_all(fn.copy_e('eid', 'eid'), reducer)
|
||||
tensor([[5, 6],
|
||||
[8, 9]])
|
||||
tensor([[3, 7, 2],
|
||||
[0, 1, 4]])
|
||||
|
||||
Essentially, node #2 and node #3 are grouped into one bucket with in-degree of 2, and node
|
||||
#0 and node #1 are grouped into one bucket with in-degree of 3. Within each bucket, the
|
||||
edges are ordered by the edge IDs for each node.
|
||||
Reference in New Issue
Block a user