Pull messages from the specified node(s)' predecessors along the specified edge type, aggregate them to update the node features. Parameters ---------- v : node IDs The node IDs. The allowed formats are: * ``int``: A single node.
(
self, v, message_func, reduce_func, apply_node_func=None, etype=None
)
| 4840 | self._set_n_repr(dtid, dstnodes, ndata) |
| 4841 | |
| 4842 | def pull( |
| 4843 | self, v, message_func, reduce_func, apply_node_func=None, etype=None |
| 4844 | ): |
| 4845 | """Pull messages from the specified node(s)' predecessors along the |
| 4846 | specified edge type, aggregate them to update the node features. |
| 4847 | |
| 4848 | Parameters |
| 4849 | ---------- |
| 4850 | v : node IDs |
| 4851 | The node IDs. The allowed formats are: |
| 4852 | |
| 4853 | * ``int``: A single node. |
| 4854 | * Int Tensor: Each element is a node ID. The tensor must have the same device type |
| 4855 | and ID data type as the graph's. |
| 4856 | * iterable[int]: Each element is a node ID. |
| 4857 | |
| 4858 | message_func : dgl.function.BuiltinFunction or callable |
| 4859 | The message function to generate messages along the edges. |
| 4860 | It must be either a :ref:`api-built-in` or a :ref:`apiudf`. |
| 4861 | reduce_func : dgl.function.BuiltinFunction or callable |
| 4862 | The reduce function to aggregate the messages. |
| 4863 | It must be either a :ref:`api-built-in` or a :ref:`apiudf`. |
| 4864 | apply_node_func : callable, optional |
| 4865 | An optional apply function to further update the node features |
| 4866 | after the message reduction. It must be a :ref:`apiudf`. |
| 4867 | etype : str or (str, str, str), optional |
| 4868 | The type name of the edges. The allowed type name formats are: |
| 4869 | |
| 4870 | * ``(str, str, str)`` for source node type, edge type and destination node type. |
| 4871 | * or one ``str`` edge type name if the name can uniquely identify a |
| 4872 | triplet format in the graph. |
| 4873 | |
| 4874 | Can be omitted if the graph has only one type of edges. |
| 4875 | |
| 4876 | Notes |
| 4877 | ----- |
| 4878 | * If some of the given nodes :attr:`v` has no in-edges, DGL does not invoke |
| 4879 | message and reduce functions for these nodes and fill their aggregated messages |
| 4880 | with zero. Users can control the filled values via :meth:`set_n_initializer`. |
| 4881 | DGL still invokes :attr:`apply_node_func` if provided. |
| 4882 | * DGL recommends using DGL's bulit-in function for the :attr:`message_func` |
| 4883 | and the :attr:`reduce_func` arguments, |
| 4884 | because DGL will invoke efficient kernels that avoids copying node features to |
| 4885 | edge features in this case. |
| 4886 | |
| 4887 | Examples |
| 4888 | -------- |
| 4889 | |
| 4890 | >>> import dgl |
| 4891 | >>> import dgl.function as fn |
| 4892 | >>> import torch |
| 4893 | |
| 4894 | **Homogeneous graph** |
| 4895 | |
| 4896 | >>> g = dgl.graph(([0, 1, 2, 3], [1, 2, 3, 4])) |
| 4897 | >>> g.ndata['x'] = torch.ones(5, 2) |
| 4898 | >>> g.pull([0, 3, 4], fn.copy_u('x', 'm'), fn.sum('m', 'h')) |
| 4899 | >>> g.ndata['h'] |