wehub-resource-sync
114 lines
7.0 KiB
Markdown
114 lines
7.0 KiB
Markdown
# 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``
|