Commit 409183bc authored by John Andrilla's avatar John Andrilla Committed by Minjie Wang
Browse files

[Doc] Edit for grammar and style (#986)

Can you add a link for the download to this sentence: You can also `download <location?>` and run the different code examples...
As with other tutorial topics, it would be helpful to add your assumptions or information in the opening section about prerequisites.
parent f1542b9d
""" """
.. currentmodule:: dgl .. currentmodule:: dgl
PageRank with DGL Message Passing PageRank with DGL message passing
================================= =================================
**Author**: `Minjie Wang <https://jermainewang.github.io/>`_, Quan Gan, Yu Gai, **Author**: `Minjie Wang <https://jermainewang.github.io/>`_, Quan Gan, Yu Gai,
Zheng Zhang Zheng Zhang
In this section we illustrate the usage of different levels of message In this tutorial, you learn how to use different levels of the message
passing API with PageRank on a small graph. In DGL, the message passing and passing API with PageRank on a small graph. In DGL, the message passing and
feature transformations are all **User-Defined Functions** (UDFs). feature transformations are **user-defined functions** (UDFs).
The goal of this tutorial: to implement PageRank using DGL message passing
interface.
""" """
############################################################################### ###############################################################################
# The PageRank Algorithm # The PageRank algorithm
# ---------------------- # ----------------------
# In each iteration of PageRank, every node (web page) first scatters its # In each iteration of PageRank, every node (web page) first scatters its
# PageRank value uniformly to its downstream nodes. The new PageRank value of # PageRank value uniformly to its downstream nodes. The new PageRank value of
...@@ -36,8 +34,8 @@ interface. ...@@ -36,8 +34,8 @@ interface.
############################################################################### ###############################################################################
# A naive implementation # A naive implementation
# ---------------------- # ----------------------
# Let us first create a graph with 100 nodes with NetworkX and convert it to a # Create a graph with 100 nodes by using ``networkx`` and then convert it to a
# :class:`DGLGraph`: # :class:`DGLGraph`.
import networkx as nx import networkx as nx
import matplotlib.pyplot as plt import matplotlib.pyplot as plt
...@@ -55,16 +53,16 @@ plt.show() ...@@ -55,16 +53,16 @@ plt.show()
############################################################################### ###############################################################################
# According to the algorithm, PageRank consists of two phases in a typical # According to the algorithm, PageRank consists of two phases in a typical
# scatter-gather pattern. We first initialize the PageRank value of each node # scatter-gather pattern. Initialize the PageRank value of each node
# to :math:`\frac{1}{N}` and store each node's out-degree as a node feature: # to :math:`\frac{1}{N}` and then store each node's out-degree as a node feature.
g.ndata['pv'] = torch.ones(N) / N g.ndata['pv'] = torch.ones(N) / N
g.ndata['deg'] = g.out_degrees(g.nodes()).float() g.ndata['deg'] = g.out_degrees(g.nodes()).float()
############################################################################### ###############################################################################
# We then define the message function, which divides every node's PageRank # Define the message function, which divides every node's PageRank
# value by its out-degree and passes the result as message to its neighbors: # value by its out-degree and passes the result as message to its neighbors.
def pagerank_message_func(edges): def pagerank_message_func(edges):
return {'pv' : edges.src['pv'] / edges.src['deg']} return {'pv' : edges.src['pv'] / edges.src['deg']}
...@@ -74,11 +72,11 @@ def pagerank_message_func(edges): ...@@ -74,11 +72,11 @@ def pagerank_message_func(edges):
# In DGL, the message functions are expressed as **Edge UDFs**. Edge UDFs # In DGL, the message functions are expressed as **Edge UDFs**. Edge UDFs
# take in a single argument ``edges``. It has three members ``src``, ``dst``, # take in a single argument ``edges``. It has three members ``src``, ``dst``,
# and ``data`` for accessing source node features, destination node features, # and ``data`` for accessing source node features, destination node features,
# and edge features respectively. Here, the function computes messages only # and edge features. Here, the function computes messages only
# from source node features. # from source node features.
# #
# Next, we define the reduce function, which removes and aggregates the # Define the reduce function, which removes and aggregates the
# messages from its ``mailbox``, and computes its new PageRank value: # messages from its ``mailbox``, and computes its new PageRank value.
def pagerank_reduce_func(nodes): def pagerank_reduce_func(nodes):
msgs = torch.sum(nodes.mailbox['pv'], dim=1) msgs = torch.sum(nodes.mailbox['pv'], dim=1)
...@@ -89,7 +87,7 @@ def pagerank_reduce_func(nodes): ...@@ -89,7 +87,7 @@ def pagerank_reduce_func(nodes):
############################################################################### ###############################################################################
# The reduce functions are **Node UDFs**. Node UDFs have a single argument # The reduce functions are **Node UDFs**. Node UDFs have a single argument
# ``nodes``, which has two members ``data`` and ``mailbox``. ``data`` # ``nodes``, which has two members ``data`` and ``mailbox``. ``data``
# contains the node features while ``mailbox`` contains all incoming message # contains the node features and ``mailbox`` contains all incoming message
# features, stacked along the second dimension (hence the ``dim=1`` argument). # features, stacked along the second dimension (hence the ``dim=1`` argument).
# #
# The message UDF works on a batch of edges, whereas the reduce UDF works on # The message UDF works on a batch of edges, whereas the reduce UDF works on
...@@ -98,7 +96,7 @@ def pagerank_reduce_func(nodes): ...@@ -98,7 +96,7 @@ def pagerank_reduce_func(nodes):
# #
# .. image:: https://i.imgur.com/kIMiuFb.png # .. image:: https://i.imgur.com/kIMiuFb.png
# #
# We register the message function and reduce function, which will be called # Register the message function and reduce function, which will be called
# later by DGL. # later by DGL.
g.register_message_func(pagerank_message_func) g.register_message_func(pagerank_message_func)
...@@ -106,8 +104,8 @@ g.register_reduce_func(pagerank_reduce_func) ...@@ -106,8 +104,8 @@ g.register_reduce_func(pagerank_reduce_func)
############################################################################### ###############################################################################
# The algorithm is then very straight-forward. Here is the code for one # The algorithm is straightforward. Here is the code for one
# PageRank iteration: # PageRank iteration.
def pagerank_naive(g): def pagerank_naive(g):
# Phase #1: send out messages along all edges. # Phase #1: send out messages along all edges.
...@@ -119,12 +117,12 @@ def pagerank_naive(g): ...@@ -119,12 +117,12 @@ def pagerank_naive(g):
############################################################################### ###############################################################################
# Improvement with batching semantics # Batching semantics for a large graph
# ----------------------------------- # -----------------------------------
# The above code does not scale to large graph because it iterates over all # The above code does not scale to a large graph because it iterates over all
# the nodes. DGL solves this by letting user compute on a *batch* of nodes or # the nodes. DGL solves this by allowing you to compute on a *batch* of nodes or
# edges. For example, the following codes trigger message and reduce functions # edges. For example, the following codes trigger message and reduce functions
# on multiple nodes and edges at once. # on multiple nodes and edges at one time.
def pagerank_batch(g): def pagerank_batch(g):
g.send(g.edges()) g.send(g.edges())
...@@ -132,52 +130,51 @@ def pagerank_batch(g): ...@@ -132,52 +130,51 @@ def pagerank_batch(g):
############################################################################### ###############################################################################
# Note that we are still using the same reduce function ``pagerank_reduce_func``, # You are still using the same reduce function ``pagerank_reduce_func``,
# where ``nodes.mailbox['pv']`` is a *single* tensor, stacking the incoming # where ``nodes.mailbox['pv']`` is a *single* tensor, stacking the incoming
# messages along the second dimension. # messages along the second dimension.
# #
# Naturally, one will wonder if this is even possible to perform reduce on all # You might wonder if this is even possible to perform reduce on all
# nodes in parallel, since each node may have different number of incoming # nodes in parallel, since each node may have different number of incoming
# messages and one cannot really "stack" tensors of different lengths together. # messages and you cannot really "stack" tensors of different lengths together.
# In general, DGL solves the problem by grouping the nodes by the number of # In general, DGL solves the problem by grouping the nodes by the number of
# incoming messages, and calling the reduce function for each group. # incoming messages, and calling the reduce function for each group.
############################################################################### ###############################################################################
# More improvement with higher level APIs # Use higher-level APIs for efficiency
# --------------------------------------- # ---------------------------------------
# DGL provides many routines that combines basic ``send`` and ``recv`` in # DGL provides many routines that combine basic ``send`` and ``recv`` in
# various ways. They are called **level-2 APIs**. For example, the PageRank # various ways. These routines are called **level-2 APIs**. For example, the next code example
# example can be further simplified as follows: # shows how to further simplify the PageRank example with such an API.
def pagerank_level2(g): def pagerank_level2(g):
g.update_all() g.update_all()
############################################################################### ###############################################################################
# Besides ``update_all``, we also have ``pull``, ``push``, and ``send_and_recv`` # In addition to ``update_all``, you can use ``pull``, ``push``, and ``send_and_recv``
# in this level-2 category. Please refer to the :doc:`API reference <../../api/python/graph>` # in this level-2 category. For more information, see :doc:`API reference <../../api/python/graph>`.
# for more details.
############################################################################### ###############################################################################
# Even more improvement with DGL builtin functions # Use DGL ``builtin`` functions for efficiency
# ------------------------------------------------ # ------------------------------------------------
# As some of the message and reduce functions are very commonly used, DGL also # Some of the message and reduce functions are used frequently. For this reason, DGL also
# provides **builtin functions**. For example, two builtin functions can be # provides ``builtin`` functions. For example, two ``builtin`` functions can be
# used in the PageRank example. # used in the PageRank example.
# #
# * :func:`dgl.function.copy_src(src, out) <function.copy_src>` # * :func:`dgl.function.copy_src(src, out) <function.copy_src>` - This
# is an edge UDF that computes the # code example is an edge UDF that computes the
# output using the source node feature data. User needs to specify the name of # output using the source node feature data. To use this, specify the name of
# the source feature data (``src``) and the output name (``out``). # the source feature data (``src``) and the output name (``out``).
# #
# * :func:`dgl.function.sum(msg, out) <function.sum>` is a node UDF # * :func:`dgl.function.sum(msg, out) <function.sum>` - This code example is a node UDF
# that sums the messages in # that sums the messages in
# the node's mailbox. User needs to specify the message name (``msg``) and the # the node's mailbox. To use this, specify the message name (``msg``) and the
# output name (``out``). # output name (``out``).
# #
# For example, the PageRank example can be rewritten as following: # The following PageRank example shows such functions.
import dgl.function as fn import dgl.function as fn
...@@ -189,20 +186,20 @@ def pagerank_builtin(g): ...@@ -189,20 +186,20 @@ def pagerank_builtin(g):
############################################################################### ###############################################################################
# Here, we directly provide the UDFs to the :func:`update_all <DGLGraph.update_all>` # In the previous example code, you directly provide the UDFs to the :func:`update_all <DGLGraph.update_all>`
# as its arguments. # as its arguments.
# This will override the previously registered UDFs. # This will override the previously registered UDFs.
# #
# In addition to cleaner code, using builtin functions also gives DGL the # In addition to cleaner code, using ``builtin`` functions also gives DGL the
# opportunity to fuse operations together, resulting in faster execution. For # opportunity to fuse operations together. This results in faster execution. For
# example, DGL will fuse the ``copy_src`` message function and ``sum`` reduce # example, DGL will fuse the ``copy_src`` message function and ``sum`` reduce
# function into one sparse matrix-vector (spMV) multiplication. # function into one sparse matrix-vector (spMV) multiplication.
# #
# `This section <spmv_>`_ describes why spMV can speed up the scatter-gather # `The following section <spmv_>`_ describes why spMV can speed up the scatter-gather
# phase in PageRank. For more details about the builtin functions in DGL, # phase in PageRank. For more details about the ``builtin`` functions in DGL,
# please read the :doc:`API reference <../../api/python/function>`. # see :doc:`API reference <../../api/python/function>`.
# #
# You can also download and run the codes to feel the difference. # You can also download and run the different code examples to see the differences.
for k in range(K): for k in range(K):
# Uncomment the corresponding line to select different version. # Uncomment the corresponding line to select different version.
...@@ -218,9 +215,9 @@ print(g.ndata['pv']) ...@@ -218,9 +215,9 @@ print(g.ndata['pv'])
# #
# Using spMV for PageRank # Using spMV for PageRank
# ----------------------- # -----------------------
# Using builtin functions allows DGL to understand the semantics of UDFs and # Using ``builtin`` functions allows DGL to understand the semantics of UDFs.
# thus allows more efficient implementation for you. For example, in the case # This allows you to create an efficient implementation. For example, in the case
# of PageRank, one common trick to accelerate it is using its linear algebra # of PageRank, one common method to accelerate it is by using its linear algebra
# form. # form.
# #
# .. math:: # .. math::
...@@ -230,28 +227,24 @@ print(g.ndata['pv']) ...@@ -230,28 +227,24 @@ print(g.ndata['pv'])
# Here, :math:`\mathbf{R}^k` is the vector of the PageRank values of all nodes # Here, :math:`\mathbf{R}^k` is the vector of the PageRank values of all nodes
# at iteration :math:`k`; :math:`\mathbf{A}` is the sparse adjacency matrix # at iteration :math:`k`; :math:`\mathbf{A}` is the sparse adjacency matrix
# of the graph. # of the graph.
# Computing this equation is quite efficient because there exists efficient # Computing this equation is quite efficient because there is an efficient
# GPU kernel for the *sparse-matrix-vector-multiplication* (spMV). DGL # GPU kernel for the sparse matrix-vector multiplication (spMV). DGL
# detects whether such optimization is available through the builtin # detects whether such optimization is available through the ``builtin``
# functions. If the certain combination of builtins can be mapped to a spMV # functions. If a certain combination of ``builtin`` can be mapped to an spMV
# kernel (e.g. the pagerank example), DGL will use it automatically. As a # kernel (e.g., the PageRank example), DGL uses it automatically. We recommend
# result, *we recommend using builtin functions whenever it is possible*. # using ``builtin`` functions whenever possible.
############################################################################### ###############################################################################
# Next steps # Next steps
# ---------- # ----------
# #
# * Learn how to use DGL builtin functions to write more efficient message passing # * Learn how to use DGL (:doc:`builtin functions<../../features/builtin>`) to write
# (:doc:`link<../../features/builtin>`). # more efficient message passing.
# * Check out the :doc:`overview page<../models/index>` # * To see model tutorials, see the :doc:`overview page<../models/index>`.
# of all the model tutorials. # * To learn about Graph Neural Networks, see :doc:`GCN tutorial<../models/1_gnn/1_gcn>`.
# * Would like to know more about Graph Neural Networks? Start with the # * To see how DGL batches multiple graphs, see :doc:`TreeLSTM tutorial<../models/2_small_graph/3_tree-lstm>`.
# :doc:`GCN tutorial<../models/1_gnn/1_gcn>`. # * Play with some graph generative models by following tutorial for :doc:`Deep Generative Model of Graphs<../models/3_generative_model/5_dgmg>`.
# * Would like to know how DGL batches multiple graphs? Start with the # * To learn how traditional models are interpreted in a view of graph, see
# :doc:`TreeLSTM tutorial<../models/2_small_graph/3_tree-lstm>`. # the tutorials on :doc:`CapsuleNet<../models/4_old_wines/2_capsule>` and
# * Would like to play with some graph generative models? Start with our tutorial
# on the :doc:`Deep Generative Model of Graphs<../models/3_generative_model/5_dgmg>`.
# * Would like to see how traditional models are interpreted in a view of graph?
# Check out our tutorials on :doc:`CapsuleNet<../models/4_old_wines/2_capsule>` and
# :doc:`Transformer<../models/4_old_wines/7_transformer>`. # :doc:`Transformer<../models/4_old_wines/7_transformer>`.
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