migrate-guide-0.5.md

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:

   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.

2. 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.

     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.

3. dgl.bipartite is removed.

   • To create a uni-directional bipartite graph, use dgl.heterograph. E.g.,

     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.

4. 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.,

     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()})

5. dgl.hetero_from_relations is removed. Use dgl.heterograph instead.

6. 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.

7. 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.

     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())``.

8. The reduce function dgl.function.prod is removed.

9. 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).
2. 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.
3. dgl.to_simple_graph -> dgl.to_simple.
4. dgl.to_homo -> dgl.to_homogeneous.
5. dgl.to_hetero -> dgl.to_heterogeneous.
6. dgl.as_heterograph and dgl.as_immutable_graph are deprecated as dgl.DGLGraph and dgl.DGLHeteroGraph are now merged.
7. dgl.batch_hetero -> dgl.batch
8. dgl.unbatch_hetero -> dgl.unbatch
9. The node_attrs / edge_attrs arguments of dgl.batch are renamed to ndata / edata.
10. 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:

# 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