migrate guide

docs/migrate-guide-0.5.md

@@ -0,0 +1,113 @@
+# Migration Guide for DGL 0.5
+
+## Breaking changes
+
+The following changes may break existing codes if the related APIs are used. Note that **most of the removed APIs have quite rare use cases** and have quite easy replacements.
+
+1. DGLGraph now requires the graph structure and feature data to have the same device placement. If the given node/edge feature tensors have different devices as the graph’s, dgl.ndata and dgl.edata will raise an error as follow:
+    ```bash
+    dgl._ffi.base.DGLError: Cannot assign node feature "x" on device cpu to a graph on device cuda:0.
+    Call DGLGraph.to() to copy the graph to the same device.
+    ```
+    To fix it, copy either the graph (using the `DGLGraph.to` API) or the feature tensors to the same device.
+
+1. Changes to `dgl.graph`:
+    * No longer accept SciPy matrix/NetworkX graph as the input data. Use `dgl.from_scipy`/`dgl.from_networkx` instead.
+    * `ntype` and `etype` are removed from the arguments. To construct graphs with named node/edge types, use `dgl.heterograph`.
+        ```python
+        g = dgl.heterograph(('user', 'follows', 'user') : ...)
+        ```
+    * `validate` is removed from the arguments. DGL now always checks whether the num_nodes is greater than the largest node ID if specified.
+1. `dgl.bipartite` is removed.
+    * To create a uni-directional bipartite graph, use `dgl.heterograph`. E.g.,
+        ```python
+        g = dgl.hetrograph(('user', 'rates', 'movie'): ...)
+        ```
+    * To create a uni-directional bipartite graph from a SciPy matrix, use the new API `dgl.bipartite_from_scipy`.
+    * To create a uni-directional bipartite graph from a NetworkX graph, use the new API `dgl.bipartite_from_networkx`.
+1. Changes to `dgl.heterograph`:
+    * No longer accept SciPy matrix/NetworkX graph as the input data. Use the `from_*` APIs to create graphs first and then pass their edges to the `dgl.heterograph` API. E.g.,
+        ```python
+        nx_g = ...  # some networkx graph
+        spmat = ...  # some scipy matrix
+        g1 = dgl.from_networkx(nx_g)
+        g2 = dgl.bipartite_from_scipy(spmat)
+        g = dgl.heterograph({('user', 'follows', 'user') : g1.edges(),
+                             ('user', 'rates', 'movie') : g2.edges()})
+        ```
+1. `dgl.hetero_from_relations` is removed. Use `dgl.heterograph` instead.
+1. From 0.5, subgraphs extracted via DGL APIs automatically inherits node and edge features from the parent graph. DGL also saves the original nodes/edge IDs in `subg.ndata[dgl.NID]` and `subg.edata[dgl.EID]` if nodes/edges are relabeled. This new behavior makes the following `DGLGraph` methods useless and we thus remove them:
+    * `DGLGraph.parent`, `DGLGraph.parent_nid`, `DGLGraph.parent_eid`, `DGLGraph.map_to_subgraph_nid`, `DGLGraph.copy_from_parent`, `DGLGraph.copy_to_parent` and `DGLGraph.detach_parent`.
+1. Other removed DGLGraph APIs:
+    * `DGLGraph.from_networkx`. Use `dgl.from_networkx` to construct a DGLGraph from a NetworkX graph.
+    * `DGLGraph.from_scipy_sparse_matrix`. Use `dgl.from_scipy` to construct a DGLGraph from a SciPy matrix.
+    * `DGLGraph.register_apply_node_func` , `DGLGraph.register_apply_edge_func`, `DGLGraph.register_message_func` and `DGLGraph.register_reduce_func`. Please specify them directly as the arguments of the message passing APIs.
+        ```python
+        g = ...  # some graph
+        # before 0.5
+        g.register_message_func(mfunc)
+        g.register_reduce_func(rfunc)
+        g.update_all()
+        
+        # starting from 0.5
+        g.update_all(mfunc, rfunc)
+        ```
+    * `DGLGraph.group_apply_edges`. To normalize edge weights within the neighborhood of each destination node, use `dgl.nn.edge_softmax`. To normalize edge weights within the neighborhood of each source node, use `dgl.reverse` first before the edge softmax.
+    * `DGLGraph.send` and `DGLGraph.recv`. There are rarely any cases where send and recv must be invoked separately. Use `DGLGraph.send_and_recv` or `DGLGraph.update_all` for message passing.
+    * `DGLGraph.multi_recv`, `DGLGraph.multi_pull`, `DGLGraph.multi_send_and_recv`. To perform message passing on a part  of the nodes and edges, use `dgl.node_subgraph` or `dgl.edge_subgraph` to extract the subset first and then call `DGLGraph.multi_update_all`.
+    * `DGLGraph.clear`. Use `dgl.graph(([], []))`` to create a new empty graph.
+    * `DGLGraph.subgraphs`. Use `DGLGraph.subgraph`.
+    * `DGLGraph.batch_num_nodes` and `DGLGraph.batch_num_edges` are now functions that accept node/edge type as the only argument for getting batching information of a heterograph.
+    * `DGLGraph.flatten`. To create a new graph without batching information, use `new_g = gl.graph(old_g.edges())``.
+1. The reduce function `dgl.function.prod` is removed.
+1. `dgl.add_self_loop` will NOT remove existing self loops automatically. It is recommanded to call `dgl.remove_self_loop` before invoking `dgl.add_self_loop`.
+
+
+
+## Deprecations
+
+Will not break old codes but will throw deprecation warning.
+
+### Core APIs
+
+1. Creating a graph using `dgl.DGLGraph(data)` is deprecated. Use `dgl.graph(data)`.
+1. Deprecated `DGLGraph` methods:
+    - `DGLGraph.to_networkx` -> `dgl.to_networkx`
+    - `DGLGraph.readonly` and `DGLGraph.is_readonly`. Before 0.5, this flag is a hint for more efficient implementation. From 0.5, the efficiency issue has been resolved so they become useless. 
+    - `DGLGraph.__len__` -> `DGLGraph.number_of_nodes`
+    - `dgl.DGLGraph.__contains__` -> `DGLGraph.has_nodes`
+    - `DGLGraph.add_node` -> `DGLGraph.add_nodes`
+    - `DGLGraph.add_edge` -> `DGLGraph.add_edges`
+    - `DGLGraph.has_node` -> `DGLGraph.has_nodes`
+    - `DGLGraph.has_edge_between` -> `DGLGraph.has_edges_between` 
+    - `DGLGraph.edge_id` -> `dgl.DGLGraph.edge_ids`.
+    - `DGLGraph.in_degree` -> `dgl.DGLGraph.in_degrees`.
+    - `DGLGraph.out_degree` -> `dgl.DGLGraph.out_degrees`.
+1. `dgl.to_simple_graph` -> `dgl.to_simple`.
+1. `dgl.to_homo` -> `dgl.to_homogeneous`.
+1. `dgl.to_hetero` -> `dgl.to_heterogeneous`.
+1. `dgl.as_heterograph` and `dgl.as_immutable_graph` are deprecated as `dgl.DGLGraph` and `dgl.DGLHeteroGraph` are now merged.
+1. `dgl.batch_hetero` -> `dgl.batch`
+1. `dgl.unbatch_hetero` -> `dgl.unbatch`
+1. The `node_attrs` / `edge_attrs` arguments of `dgl.batch` are renamed to `ndata` / `edata`.
+1. The arguments `share_ndata` and `share_edata` of `dgl.reverse` are renamed to `copy_ndata` and `copy_edata`.
+
+### Dataset APIs
+
+For all the current datsets, their class attributes such as `graph`, `feat`, etc. are deprecated. The recommended usage is to get them from each sample:
+```python
+# Before 0.5
+dataset = dgl.data.CoraFull()
+g = dataset.graph
+feat = dataset.feat
+...
+
+# From 0.5
+dataset = dgl.data.CoraFullDataset()  # in 0.5, all the classes have a "Dataset" in the name.
+g = dataset[0]  # is directly a DGLGraph object
+feat = g.ndata['feat']
+...
+```
+
+**Other changes**
+* ``dgl.data.SST`` is deprecated and replaced by ``dgl.data.SSTDataset``. The attribute ``trees`` is deprecated and replaced by ``__getitem__``. The attribute ``num_vocabs`` is deprecated and replaced by ``vocab_size``