Convert a graph into a bipartite-structured *block* for message passing. A block is a graph consisting of two sets of nodes: the *source* nodes and *destination* nodes. The source and destination nodes can have multiple node types. All the edges connect from source nodes to destinatio
(g, dst_nodes=None, include_dst_in_src=True, src_nodes=None)
| 26 | |
| 27 | |
| 28 | def to_block(g, dst_nodes=None, include_dst_in_src=True, src_nodes=None): |
| 29 | """Convert a graph into a bipartite-structured *block* for message passing. |
| 30 | |
| 31 | A block is a graph consisting of two sets of nodes: the |
| 32 | *source* nodes and *destination* nodes. The source and destination nodes can have multiple |
| 33 | node types. All the edges connect from source nodes to destination nodes. |
| 34 | |
| 35 | Specifically, the source nodes and destination nodes will have the same node types as the |
| 36 | ones in the original graph. DGL maps each edge ``(u, v)`` with edge type |
| 37 | ``(utype, etype, vtype)`` in the original graph to the edge with type |
| 38 | ``etype`` connecting from node ID ``u`` of type ``utype`` in the source side to node |
| 39 | ID ``v`` of type ``vtype`` in the destination side. |
| 40 | |
| 41 | For blocks returned by :func:`to_block`, the destination nodes of the block will only |
| 42 | contain the nodes that have at least one inbound edge of any type. The source nodes |
| 43 | of the block will only contain the nodes that appear in the destination nodes, as well |
| 44 | as the nodes that have at least one outbound edge connecting to one of the destination nodes. |
| 45 | |
| 46 | The destination nodes are specified by the :attr:`dst_nodes` argument if it is not None. |
| 47 | |
| 48 | Parameters |
| 49 | ---------- |
| 50 | graph : DGLGraph |
| 51 | The graph. Can be either on CPU or GPU. |
| 52 | dst_nodes : Tensor or dict[str, Tensor], optional |
| 53 | The list of destination nodes. |
| 54 | |
| 55 | If a tensor is given, the graph must have only one node type. |
| 56 | |
| 57 | If given, it must be a superset of all the nodes that have at least one inbound |
| 58 | edge. An error will be raised otherwise. |
| 59 | include_dst_in_src : bool |
| 60 | If False, do not include destination nodes in source nodes. |
| 61 | |
| 62 | (Default: True) |
| 63 | |
| 64 | src_nodes : Tensor or disct[str, Tensor], optional |
| 65 | The list of source nodes (and prefixed by destination nodes if |
| 66 | `include_dst_in_src` is True). |
| 67 | |
| 68 | If a tensor is given, the graph must have only one node type. |
| 69 | |
| 70 | Returns |
| 71 | ------- |
| 72 | DGLBlock |
| 73 | The new graph describing the block. |
| 74 | |
| 75 | The node IDs induced for each type in both sides would be stored in feature |
| 76 | ``dgl.NID``. |
| 77 | |
| 78 | The edge IDs induced for each type would be stored in feature ``dgl.EID``. |
| 79 | |
| 80 | Raises |
| 81 | ------ |
| 82 | DGLError |
| 83 | If :attr:`dst_nodes` is specified but it is not a superset of all the nodes that |
| 84 | have at least one inbound edge. |
| 85 |