[Doc][Model] example folder doc and model summary (dmlc#259)

* update example readme

* mx example readme

* add results in readme

* mx rgcn readme

examples/mxnet/README.md

@@ -0,0 +1,7 @@
+# Model Examples using DGL (w/ MXNet backend)
+
+Each model is hosted in their own folders. Please read their README.md to see how to
+run them.
+
+To understand step-by-step how these models are implemented in DGL. Check out our
+[tutorials](https://docs.dgl.ai/tutorials/models/index.html)

examples/mxnet/rgcn/README.md

@@ -9,17 +9,17 @@ Two extra python packages are needed for this example:
 Example code was tested with rdflib 4.2.2 and pandas 0.23.4
 
 ### Entity Classification
-AIFB:
+AIFB: accuracy 97.22% (DGL), 95.83% (paper)
 ```
 DGLBACKEND=mxnet python entity_classify.py -d aifb --testing --gpu 0
 ```
 
-MUTAG:
+MUTAG: accuracy 76.47% (DGL), 73.23% (paper)
 ```
 DGLBACKEND=mxnet python entity_classify.py -d mutag --l2norm 5e-4 --n-bases 40 --testing --gpu 0
 ```
 
-BGS:
+BGS: accuracy 79.31% (DGL, n-basese=20, OOM when >20), 83.10% (paper)
 ```
 DGLBACKEND=mxnet python entity_classify.py -d bgs --l2norm 5e-4 --n-bases 20 --testing --gpu 0 --relabel
 ```

examples/pytorch/README.md

@@ -1,7 +1,21 @@
-# DGL example models
+# Model Examples using DGL (w/ Pytorch backend)
 
-## Dataset
-gat.py and gcn.py use real dataset, please download citeseer/cora/pubmed dataset from:
-https://github.com/tkipf/gcn/tree/master/gcn/data
+Each model is hosted in their own folders. Please read their README.md to see how to
+run them.
 
-dataset.py (adapted from tkipf/gcn) assumes that there is a "data" folder under current directory
+To understand step-by-step how these models are implemented in DGL. Check out our
+[tutorials](https://docs.dgl.ai/tutorials/models/index.html)
+
+## Model summary
+
+Here is a summary of the model accuracy and training speed. Our testbed is Amazon EC2 p3.2x instance (w/ V100 GPU).
+
+| Model | Reported <br> Accuracy | DGL <br> Accuracy | Author's training speed (epoch time) | DGL speed (epoch time) | Improvement |
+| ----- | ----------------- | ------------ | ------------------------------------ | ---------------------- | ----------- |
+| GCN   | 81.5% | 81.0% | 0.0051s (TF) | 0.0042s | 1.17x |
+| TreeLSTM | 51.0% | 51.72% | 14.02s (DyNet) | 3.18s | 4.3x |
+| R-GCN <br> (classification) | 73.23% | 73.53% | 0.2853s (Theano) | 0.0273s | 10.4x |
+| R-GCN <br> (link prediction) | 0.158 | 0.151 | 2.204s (TF) | 0.633s | 3.5x |
+| JTNN | 96.44% | 96.44% | 1826s (Pytorch) | 743s | 2.5x |
+| LGNN | 94% | 94% | n/a | 1.45s | n/a |
+| DGMG | 84% | 90% | n/a | 1 hr | n/a |

examples/pytorch/gcn/README.md

@@ -5,52 +5,20 @@ Graph Convolutional Networks (GCN)
 - Author's code repo: [https://github.com/tkipf/gcn](https://github.com/tkipf/gcn). Note that the original code is 
 implemented with Tensorflow for the paper. 
 
-The folder contains two different implementations using DGL.
+Codes
+-----
+The folder contains two implementations of GCN. `gcn_batch.py` uses user-defined
+message and reduce functions. `gcn_spmv.py` uses DGL's builtin functions so
+SPMV optimization could be applied.
 
-Batched GCN (gcn.py)
------------
-Defining the model on only one node and edge makes it hard to fully utilize GPUs. As a result, we allow users to define model on a *batch of* nodes and edges.
+Results
+-------
 
-* The message function `gcn_msg` computes the message for a batch of edges. Here, the `src` argument is the batched representation of the source endpoints of the edges. The function simply returns the source node representations.
-  ```python
-  def gcn_msg(edge):
-    # edge.src contains the node data on the source node.
-    # It's a dictionary. edge.src['h'] is a tensor of shape (B, D).
-    # B is the number of edges being batched.
-    return {'m': edge.src['h']}
-  ```
-* The reduce function `gcn_reduce` also accumulates messages for a batch of nodes. We batch the messages on the second dimension for the `msgs` argument, 
-which for example can correspond to the neighbors of the nodes:
-  ```python
-  def gcn_reduce(node):
-    # node.mailbox contains messages from `gcn_msg`.
-    # node.mailbox['m'] is a tensor of shape (B, deg, D). B is the number of nodes in the batch;
-    #  deg is the number of messages; D is the message tensor dimension. DGL gaurantees
-    #  that all the nodes in a batch have the same in-degrees (through "degree-bucketing").
-    # Reduce on the second dimension is equal to sum up all the in-coming messages.
-    return {'accum': mx.nd.sum(node.mailbox['m'], 1)}
-  ```
-* The update function `NodeUpdateModule` computes the new new node representation `h` using non-linear transformation on the reduced messages.
-  ```python
-  class NodeUpdateModule(gluon.Block):
-    def __init__(self, out_feats, activation=None):
-      super(NodeUpdateModule, self).__init__()
-      self.linear = gluon.nn.Dense(out_feats, activation=activation)
-
-    def forward(self, node):
-      accum = self.linear(node.data['accum'])
-      return {'h': mx.nd.concat(node.data['h'], accum, dim=1)}
-  ```
-
-After defining the functions on each node/edge, the message passing is triggered by calling `update_all` on the DGLGraph object (in GCN module).
-```python
-self.g.update_all(gcn_msg, gcn_reduce, layer)`
+Run with following (available dataset: "cora", "citeseer", "pubmed")
+```bash
+python gcn_spmv.py --dataset cora --gpu 0
 ```
 
-Batched GCN with spMV optimization (gcn_spmv.py)
------------
-Batched computation is much more efficient than naive vertex-centric approach, but is still not ideal. For example, the batched message function needs to look up source node data and save it on edges. Such kind of lookups is very common and incurs extra memory copy operations. In fact, the message and reduce phase of GCN model can be fused into one sparse-matrix-vector multiplication (spMV). Therefore, DGL provides many built-in message/reduce functions so we can figure out the chance of optimization. In gcn_spmv.py, user only needs to write update module and trigger the message passing as follows:
-```python
-self.g.update_all(fn.copy_src(src='h', out='m'), fn.sum(msg='m', out='h'), layer)
-```
-Here, `'fn.copy_src'` and `'fn.sum'` are the builtin message and reduce functions that perform the same operations as `gcn_msg` and `gcn_reduce` in gcn.py.
+* cora: ~0.810 (0.79-0.83) (paper: 0.815)
+* citeseer: 0.707 (paper: 0.703)
+* pubmed: 0.792 (paper: 0.790)