Skip to content

GitLab

You need to sign in or sign up before continuing.
Unverified Commit 8a07ab77 authored by Minjie Wang's avatar Minjie Wang Committed by GitHub
Browse files

[Doc] Tutorials re-organization (#2683) 

* reorg

* change titles

* rm some stale API doc; minor fix

* fix docs

* add warning

* rm new-tutorial run in ci

* lint
parent 0fc64952
Hide whitespace changes
Inline Side-by-side
Showing with 50 additions and 611 deletions
docs/source/api/python/dgl.dataloading.rst
View file @ 8a07ab77
...@@ -19,6 +19,7 @@ and an ``EdgeDataLoader`` for edge/link prediction task. ...@@ -19,6 +19,7 @@ and an ``EdgeDataLoader`` for edge/link prediction task.
.. autoclass:: GraphDataLoader .. autoclass:: GraphDataLoader
.. _api-dataloading-neighbor-sampling: .. _api-dataloading-neighbor-sampling:
Neighbor Sampler Neighbor Sampler
----------------------------- -----------------------------
.. currentmodule:: dgl.dataloading.neighbor .. currentmodule:: dgl.dataloading.neighbor
......
docs/source/api/python/dgl.rst
View file @ 8a07ab77
...@@ -114,10 +114,33 @@ Utilities for computing adjacency matrix and Lapacian matrix. ...@@ -114,10 +114,33 @@ Utilities for computing adjacency matrix and Lapacian matrix.
khop_adj khop_adj
laplacian_lambda_max laplacian_lambda_max
Traversals Graph Traversal & Message Propagation
------------------------------------------ ------------------------------------------
Utilities for traversing graphs. 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:: .. autosummary::
:toctree: ../../generated/ :toctree: ../../generated/
......
docs/source/api/python/graph.rst deleted 100644 → 0
View file @ 0fc64952
.. _apigraph:
dgl.DGLGraph
=========================================
.. currentmodule:: dgl
.. autoclass:: DGLGraph
Adding nodes and edges
----------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.add_nodes
DGLGraph.add_edge
DGLGraph.add_edges
DGLGraph.clear
Querying graph structure
------------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.number_of_nodes
DGLGraph.number_of_edges
DGLGraph.__len__
DGLGraph.is_multigraph
DGLGraph.has_node
DGLGraph.has_nodes
DGLGraph.__contains__
DGLGraph.has_edge_between
DGLGraph.has_edges_between
DGLGraph.predecessors
DGLGraph.successors
DGLGraph.edge_id
DGLGraph.edge_ids
DGLGraph.find_edges
DGLGraph.in_edges
DGLGraph.out_edges
DGLGraph.all_edges
DGLGraph.in_degree
DGLGraph.in_degrees
DGLGraph.out_degree
DGLGraph.out_degrees
Querying batch summary
----------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.batch_size
DGLGraph.batch_num_nodes
DGLGraph.batch_num_edges
Querying sub-graph/parent-graph belonging information
-----------------------------------------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.parent
Removing nodes and edges
------------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.remove_nodes
DGLGraph.remove_edges
Transforming graph
------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.subgraph
DGLGraph.subgraphs
DGLGraph.edge_subgraph
DGLGraph.line_graph
DGLGraph.reverse
DGLGraph.readonly
DGLGraph.flatten
DGLGraph.detach_parent
Converting from/to other format
-------------------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.to_networkx
DGLGraph.from_networkx
DGLGraph.from_scipy_sparse_matrix
DGLGraph.adjacency_matrix
DGLGraph.adjacency_matrix_scipy
DGLGraph.incidence_matrix
Using Node/edge features
------------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.nodes
DGLGraph.edges
DGLGraph.ndata
DGLGraph.edata
DGLGraph.node_attr_schemes
DGLGraph.edge_attr_schemes
DGLGraph.set_n_initializer
DGLGraph.set_e_initializer
DGLGraph.local_var
DGLGraph.local_scope
Computing with DGLGraph
-----------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.register_message_func
DGLGraph.register_reduce_func
DGLGraph.register_apply_node_func
DGLGraph.register_apply_edge_func
DGLGraph.apply_nodes
DGLGraph.apply_edges
DGLGraph.group_apply_edges
DGLGraph.send
DGLGraph.recv
DGLGraph.send_and_recv
DGLGraph.pull
DGLGraph.push
DGLGraph.update_all
DGLGraph.prop_nodes
DGLGraph.prop_edges
DGLGraph.filter_nodes
DGLGraph.filter_edges
DGLGraph.to
Batch and Unbatch
-------------------
.. autosummary::
:toctree: ../../generated/
batch
unbatch
Mapping between subgraph and parent graph
-----------------------------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.parent_nid
DGLGraph.parent_eid
DGLGraph.map_to_subgraph_nid
Synchronize features between subgraph and parent graph
------------------------------------------------------
.. autosummary::
:toctree: ../../generated/
DGLGraph.copy_from_parent
DGLGraph.copy_to_parent
docs/source/api/python/graph_store.rst deleted 100644 → 0
View file @ 0fc64952
.. _apigraphstore:
Graph Store -- Graph for multi-processing and distributed training
==================================================================
.. currentmodule:: dgl.contrib.graph_store
.. autoclass:: SharedMemoryDGLGraph
Querying the distributed setting
--------------------------------
.. autosummary::
:toctree: ../../generated/
SharedMemoryDGLGraph.num_workers
SharedMemoryDGLGraph.worker_id
SharedMemoryDGLGraph.destroy
Using Node/edge features
------------------------
.. autosummary::
:toctree: ../../generated/
SharedMemoryDGLGraph.init_ndata
SharedMemoryDGLGraph.init_edata
Computing with Graph store
--------------------------
.. autosummary::
:toctree: ../../generated/
SharedMemoryDGLGraph.apply_nodes
SharedMemoryDGLGraph.apply_edges
SharedMemoryDGLGraph.group_apply_edges
SharedMemoryDGLGraph.recv
SharedMemoryDGLGraph.send_and_recv
SharedMemoryDGLGraph.pull
SharedMemoryDGLGraph.push
SharedMemoryDGLGraph.update_all
Construct a graph store
-----------------------
.. autofunction:: dgl.contrib.graph_store.create_graph_store_server
.. autofunction:: dgl.contrib.graph_store.create_graph_from_store
docs/source/api/python/heterograph.rst deleted 100644 → 0
View file @ 0fc64952
.. _apiheterograph:
dgl.DGLHeteroGraph
=====================================================
.. currentmodule:: dgl
.. autoclass:: DGLHeteroGraph
Conversion to and from heterogeneous graphs
-----------------------------------------
.. automodule:: dgl.convert
.. currentmodule:: dgl
.. autosummary::
:toctree: ../../generated/
graph
bipartite
hetero_from_relations
heterograph
to_hetero
to_homo
to_networkx
DGLHeteroGraph.adjacency_matrix
DGLHeteroGraph.incidence_matrix
Querying metagraph structure
----------------------------
.. autosummary::
:toctree: ../../generated/
DGLHeteroGraph.ntypes
DGLHeteroGraph.etypes
DGLHeteroGraph.canonical_etypes
DGLHeteroGraph.metagraph
DGLHeteroGraph.to_canonical_etype
DGLHeteroGraph.get_ntype_id
DGLHeteroGraph.get_etype_id
Querying graph structure
------------------------
.. autosummary::
:toctree: ../../generated/
DGLHeteroGraph.number_of_nodes
DGLHeteroGraph.number_of_edges
DGLHeteroGraph.is_multigraph
DGLHeteroGraph.is_readonly
DGLHeteroGraph.has_node
DGLHeteroGraph.has_nodes
DGLHeteroGraph.has_edge_between
DGLHeteroGraph.has_edges_between
DGLHeteroGraph.predecessors
DGLHeteroGraph.successors
DGLHeteroGraph.edge_id
DGLHeteroGraph.edge_ids
DGLHeteroGraph.find_edges
DGLHeteroGraph.in_edges
DGLHeteroGraph.out_edges
DGLHeteroGraph.all_edges
DGLHeteroGraph.in_degree
DGLHeteroGraph.in_degrees
DGLHeteroGraph.out_degree
DGLHeteroGraph.out_degrees
Querying and manipulating sparse format
---------------------------------------
.. autosummary::
:toctree: ../../generated/
DGLHeteroGraph.format_in_use
DGLHeteroGraph.restrict_format
DGLHeteroGraph.to_format
Querying and manipulating index data type
-----------------------------------------
.. autosummary::
:toctree: ../../generated/
DGLHeteroGraph.idtype
DGLHeteroGraph.long
DGLHeteroGraph.int
Using Node/edge features
------------------------
.. autosummary::
:toctree: ../../generated/
DGLHeteroGraph.nodes
DGLHeteroGraph.ndata
DGLHeteroGraph.edges
DGLHeteroGraph.edata
DGLHeteroGraph.node_attr_schemes
DGLHeteroGraph.edge_attr_schemes
DGLHeteroGraph.set_n_initializer
DGLHeteroGraph.set_e_initializer
DGLHeteroGraph.local_var
DGLHeteroGraph.local_scope
Transforming graph
------------------
.. autosummary::
:toctree: ../../generated/
DGLHeteroGraph.subgraph
DGLHeteroGraph.edge_subgraph
DGLHeteroGraph.node_type_subgraph
DGLHeteroGraph.edge_type_subgraph
Computing with DGLHeteroGraph
-----------------------------
.. autosummary::
:toctree: ../../generated/
DGLHeteroGraph.apply_nodes
DGLHeteroGraph.apply_edges
DGLHeteroGraph.group_apply_edges
DGLHeteroGraph.send
DGLHeteroGraph.recv
DGLHeteroGraph.multi_recv
DGLHeteroGraph.send_and_recv
DGLHeteroGraph.multi_send_and_recv
DGLHeteroGraph.pull
DGLHeteroGraph.multi_pull
DGLHeteroGraph.push
DGLHeteroGraph.update_all
DGLHeteroGraph.multi_update_all
DGLHeteroGraph.prop_nodes
DGLHeteroGraph.prop_edges
DGLHeteroGraph.filter_nodes
DGLHeteroGraph.filter_edges
DGLHeteroGraph.to
docs/source/api/python/init.rst deleted 100644 → 0
View file @ 0fc64952
.. _apiinit:
Feature Initializer
===================
.. automodule:: dgl.init
.. autosummary::
:toctree: ../../generated/
base_initializer
zero_initializer
docs/source/api/python/nn.functional.rst 0 → 100644
View file @ 8a07ab77
.. _apinn-functional:
dgl.nn.functional
=================
.. automodule:: dgl.nn.functional
.. autosummary::
:toctree: ../../generated/
edge_softmax
docs/source/api/python/nn.rst
View file @ 8a07ab77
...@@ -10,20 +10,3 @@ dgl.nn ...@@ -10,20 +10,3 @@ dgl.nn
nn.pytorch nn.pytorch
nn.mxnet nn.mxnet
nn.tensorflow nn.tensorflow
dgl.nn.functional
=================
Edge Softmax module
-------------------
We also provide framework agnostic edge softmax module which was frequently used in
GNN-like structures, e.g.
`Graph Attention Network <https://arxiv.org/pdf/1710.10903.pdf>`_,
`Transformer <https://papers.nips.cc/paper/7181-attention-is-all-you-need.pdf>`_,
`Capsule <https://arxiv.org/pdf/1710.09829.pdf>`_, etc.
.. autosummary::
:toctree: ../../generated/
functional.edge_softmax
docs/source/api/python/nn.tensorflow.rst
View file @ 8a07ab77
.. _apinn-tensorflow: .. _apinn-tensorflow:
NN Modules (Tensorflow) NN Modules (Tensorflow)
==================== ====================================
.. _apinn-tensorflow-conv: .. _apinn-tensorflow-conv:
......
docs/source/api/python/nodeflow.rst deleted 100644 → 0
View file @ 0fc64952
.. _apinodeflow:
dgl.nodeflow (Deprecating)
==============
.. warning::
This module is going to be deprecated in favor of :ref:`api-sampling`.
.. currentmodule:: dgl
.. autoclass:: NodeFlow
Querying graph structure
------------------------
.. autosummary::
:toctree: ../../generated/
NodeFlow.num_layers
NodeFlow.num_blocks
NodeFlow.layer_size
NodeFlow.block_size
NodeFlow.layer_in_degree
NodeFlow.layer_out_degree
NodeFlow.layer_nid
NodeFlow.layer_parent_nid
NodeFlow.block_eid
NodeFlow.block_parent_eid
NodeFlow.block_edges
Converting to other format
-------------------------------
.. autosummary::
:toctree: ../../generated/
NodeFlow.block_adjacency_matrix
NodeFlow.block_incidence_matrix
Using Node/edge features
------------------------
.. autosummary::
:toctree: ../../generated/
NodeFlow.layers
NodeFlow.blocks
NodeFlow.set_n_initializer
NodeFlow.set_e_initializer
NodeFlow.node_attr_schemes
NodeFlow.edge_attr_schemes
Mapping between NodeFlow and parent graph
-----------------------------------------
.. autosummary::
:toctree: ../../generated/
NodeFlow.map_to_parent_nid
NodeFlow.map_to_parent_eid
NodeFlow.map_from_parent_nid
Synchronize features between NodeFlow and parent graph
------------------------------------------------------
.. autosummary::
:toctree: ../../generated/
NodeFlow.copy_from_parent
NodeFlow.copy_to_parent
Computing with NodeFlow
-----------------------
.. autosummary::
:toctree: ../../generated/
NodeFlow.register_message_func
NodeFlow.register_reduce_func
NodeFlow.register_apply_node_func
NodeFlow.register_apply_edge_func
NodeFlow.apply_layer
NodeFlow.apply_block
NodeFlow.block_compute
NodeFlow.prop_flow
docs/source/api/python/propagate.rst deleted 100644 → 0
View file @ 0fc64952
dgl.propagate
===============
.. automodule:: dgl.propagate
Propagate messages and perform computation 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_edges
prop_nodes_bfs
prop_nodes_topo
prop_edges_dfs
docs/source/api/python/random.rst deleted 100644 → 0
View file @ 0fc64952
.. _apirandom:
dgl.random
====================================
.. automodule:: dgl.random
Utilities used to control DGL's random number generator.
.. autosummary::
:toctree: ../../generated
seed
docs/source/api/python/readout.rst deleted 100644 → 0
View file @ 0fc64952
.. _apibatch:
dgl.readout
==================================================
.. currentmodule:: dgl
Graph Readout
-------------
.. autosummary::
:toctree: ../../generated/
sum_nodes
sum_edges
mean_nodes
mean_edges
max_nodes
max_edges
topk_nodes
topk_edges
softmax_nodes
softmax_edges
broadcast_nodes
broadcast_edges
docs/source/api/python/sampler.rst deleted 100644 → 0
View file @ 0fc64952
.. apisampler
dgl.contrib.sampling (Deprecating)
======================
.. warning::
This module is going to be deprecated in favor of :ref:`api-sampling`.
Module for sampling algorithms on graph. Each algorithm is implemented as a
data loader, which produces sampled subgraphs (called Nodeflow) at each
iteration.
.. autofunction:: dgl.contrib.sampling.sampler.NeighborSampler
.. autofunction:: dgl.contrib.sampling.sampler.LayerSampler
.. autofunction:: dgl.contrib.sampling.sampler.EdgeSampler
Distributed sampler
------------------------
.. currentmodule:: dgl.contrib.sampling.dis_sampler
.. autoclass:: SamplerPool
.. autosummary::
:toctree: ../../generated/
SamplerPool.start
SamplerPool.worker
.. autoclass:: SamplerSender
.. autosummary::
:toctree: ../../generated/
SamplerSender.send
SamplerSender.signal
.. autoclass:: SamplerReceiver
.. autosummary::
:toctree: ../../generated/
SamplerReceiver.__iter__
SamplerReceiver.__next__
docs/source/api/python/traversal.rst deleted 100644 → 0
View file @ 0fc64952
dgl.traversal
===============
.. automodule:: dgl.traversal
Graph traversal algorithms implemented as python generators, which returns the visited set
of nodes or edges 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
docs/source/conf.py
View file @ 8a07ab77
...@@ -195,14 +195,12 @@ intersphinx_mapping = { ...@@ -195,14 +195,12 @@ intersphinx_mapping = {
# sphinx gallery configurations # sphinx gallery configurations
from sphinx_gallery.sorting import FileNameSortKey from sphinx_gallery.sorting import FileNameSortKey
examples_dirs = ['../../tutorials/basics', examples_dirs = ['../../tutorials/blitz',
'../../tutorials/models', '../../tutorials/large',
'../../new-tutorial/blitz', '../../tutorials/models'] # path to find sources
'../../new-tutorial/large'] # path to find sources gallery_dirs = ['tutorials/blitz/',
gallery_dirs = ['tutorials/basics', 'tutorials/large/',
'tutorials/models', 'tutorials/models/'] # path to generate docs
'new-tutorial/blitz',
'new-tutorial/large'] # path to generate docs
reference_url = { reference_url = {
'dgl' : None, 'dgl' : None,
'numpy': 'http://docs.scipy.org/doc/numpy/', 'numpy': 'http://docs.scipy.org/doc/numpy/',
......
docs/source/guide/distributed-apis.rst
View file @ 8a07ab77
...@@ -101,13 +101,11 @@ Users can also assign a new :class:`~dgl.distributed.DistTensor` to ...@@ -101,13 +101,11 @@ Users can also assign a new :class:`~dgl.distributed.DistTensor` to
.. code:: python .. code:: python
g.ndata['train_mask'] g.ndata['train_mask'] # <dgl.distributed.dist_graph.DistTensor at 0x7fec820937b8>
<dgl.distributed.dist_graph.DistTensor at 0x7fec820937b8> g.ndata['train_mask'][0] # tensor([1], dtype=torch.uint8)
g.ndata['train_mask'][0]
tensor([1], dtype=torch.uint8)
Distributed Tensor Distributed Tensor
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
As mentioned earlier, DGL shards node/edge features and stores them in a cluster of machines. As mentioned earlier, DGL shards node/edge features and stores them in a cluster of machines.
DGL provides distributed tensors with a tensor-like interface to access the partitioned DGL provides distributed tensors with a tensor-like interface to access the partitioned
...@@ -124,7 +122,7 @@ in the cluster even if the :class:`~dgl.distributed.DistTensor` object disappear ...@@ -124,7 +122,7 @@ in the cluster even if the :class:`~dgl.distributed.DistTensor` object disappear
.. code:: python .. code:: python
tensor = dgl.distributed.DistTensor((g.number_of_nodes(), 10), th.float32, name=’test’) tensor = dgl.distributed.DistTensor((g.number_of_nodes(), 10), th.float32, name='test')
**Note**: :class:`~dgl.distributed.DistTensor` creation is a synchronized operation. All trainers **Note**: :class:`~dgl.distributed.DistTensor` creation is a synchronized operation. All trainers
have to invoke the creation and the creation succeeds only when all trainers call it. have to invoke the creation and the creation succeeds only when all trainers call it.
......
docs/source/guide/distributed-preprocessing.rst
View file @ 8a07ab77
...@@ -67,7 +67,7 @@ The following example considers nodes inside the training set and outside the tr ...@@ -67,7 +67,7 @@ The following example considers nodes inside the training set and outside the tr
.. code:: python .. code:: python
dgl.distributed.partition_graph(g, ‘graph_name’, 4, ‘/tmp/test’, balance_ntypes=g.ndata[‘train_mask’]) dgl.distributed.partition_graph(g, 'graph_name', 4, '/tmp/test', balance_ntypes=g.ndata['train_mask'])
In addition to balancing the node types, :func:`dgl.distributed.partition_graph` also allows balancing In addition to balancing the node types, :func:`dgl.distributed.partition_graph` also allows balancing
between in-degrees of nodes of different node types by specifying ``balance_edges``. This balances between in-degrees of nodes of different node types by specifying ``balance_edges``. This balances
......
docs/source/guide/index.rst
View file @ 8a07ab77
...@@ -12,3 +12,4 @@ User Guide ...@@ -12,3 +12,4 @@ User Guide
training training
minibatch minibatch
distributed distributed
mixed_precision
docs/source/guide/preface.rst deleted 100644 → 0
View file @ 0fc64952
Preface
=======
Preface chapter
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment