dgl.function¶
This subpackage hosts all the builtin functions provided by DGL. Builtin functions
are DGL’s recommended way to express different types of Chapter 2: Message Passing computation
(i.e., via update_all()
) or computing edgewise features from
nodewise features (i.e., via apply_edges()
). Builtin functions
describe the nodewise and edgewise computation in a symbolic way without any
actual computation, so DGL can analyze and map them to efficient lowlevel kernels.
Here are some examples:
import dgl
import dgl.function as fn
import torch as th
g = ... # create a DGLGraph
g.ndata['h'] = th.randn((g.num_nodes(), 10)) # each node has feature size 10
g.edata['w'] = th.randn((g.num_edges(), 1)) # each edge has feature size 1
# collect features from source nodes and aggregate them in destination nodes
g.update_all(fn.copy_u('h', 'm'), fn.sum('m', 'h_sum'))
# multiply source node features with edge weights and aggregate them in destination nodes
g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.max('m', 'h_max'))
# compute edge embedding by multiplying source and destination node embeddings
g.apply_edges(fn.u_mul_v('h', 'h', 'w_new'))
fn.copy_u
, fn.u_mul_e
, fn.u_mul_v
are builtin message functions, while fn.sum
and fn.max
are builtin reduce functions. DGL’s convention is to use u
, v
and e
to represent source nodes, destination nodes, and edges, respectively.
For example, copy_u
tells DGL to copy the source node data as the messages;
u_mul_e
tells DGL to multiply source node features with edge features.
To define a unary message function (e.g. copy_u
), specify one input feature name and one output
message name. To define a binary message function (e.g. u_mul_e
), specify
two input feature names and one output message name. During the computation,
the message function will read the data under the given names, perform computation, and return
the output using the output name. For example, the above fn.u_mul_e('h', 'w', 'm')
is
the same as the following userdefined function:
def udf_u_mul_e(edges):
return {'m' : edges.src['h'] * edges.data['w']}
To define a reduce function, one input message name and one output node feature name
need to be specified. For example, the above fn.max('m', 'h_max')
is the same as the
following userdefined function:
def udf_max(nodes):
return {'h_max' : th.max(nodes.mailbox['m'], 1)[0]}
All binary message function supports broadcasting, a mechanism for extending elementwise operations to tensor inputs with different shapes. DGL generally follows the standard broadcasting semantic by NumPy and PyTorch. Below are some examples:
import dgl
import dgl.function as fn
import torch as th
g = ... # create a DGLGraph
# case 1
g.ndata['h'] = th.randn((g.num_nodes(), 10))
g.edata['w'] = th.randn((g.num_edges(), 1))
# OK, valid broadcasting between feature shapes (10,) and (1,)
g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.sum('m', 'h_new'))
g.ndata['h_new'] # shape: (g.num_nodes(), 10)
# case 2
g.ndata['h'] = th.randn((g.num_nodes(), 5, 10))
g.edata['w'] = th.randn((g.num_edges(), 10))
# OK, valid broadcasting between feature shapes (5, 10) and (10,)
g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.sum('m', 'h_new'))
g.ndata['h_new'] # shape: (g.num_nodes(), 5, 10)
# case 3
g.ndata['h'] = th.randn((g.num_nodes(), 5, 10))
g.edata['w'] = th.randn((g.num_edges(), 5))
# NOT OK, invalid broadcasting between feature shapes (5, 10) and (5,)
# shapes are aligned from right
g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.sum('m', 'h_new'))
# case 3
g.ndata['h1'] = th.randn((g.num_nodes(), 1, 10))
g.ndata['h2'] = th.randn((g.num_nodes(), 5, 1))
# OK, valid broadcasting between feature shapes (1, 10) and (5, 1)
g.apply_edges(fn.u_add_v('h1', 'h2', 'x')) # apply_edges also supports broadcasting
g.edata['x'] # shape: (g.num_edges(), 5, 10)
# case 4
g.ndata['h1'] = th.randn((g.num_nodes(), 1, 10, 128))
g.ndata['h2'] = th.randn((g.num_nodes(), 5, 1, 128))
# OK, u_dot_v supports broadcasting but requires the last dimension to match
g.apply_edges(fn.u_dot_v('h1', 'h2', 'x'))
g.edata['x'] # shape: (g.num_edges(), 5, 10, 1)
DGL Builtin Function¶
Here is a cheatsheet of all the DGL builtin functions.
Category 
Functions 
Memo 

Unary message function 




Binary message function 












Reduce function 







Message functions¶

Builtin message function that computes message using source node feature. 

Builtin message function that computes message using edge feature. 

Builtin message function that computes a message on an edge by performing elementwise add between features of u and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise sub between features of u and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise mul between features of u and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise div between features of u and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise add between features of u and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise sub between features of u and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise mul between features of u and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise div between features of u and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise add between features of v and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise sub between features of v and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise mul between features of v and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise div between features of v and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise add between features of v and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise sub between features of v and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise mul between features of v and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise div between features of v and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise add between features of e and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise sub between features of e and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise mul between features of e and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise div between features of e and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise add between features of e and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise sub between features of e and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise mul between features of e and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise div between features of e and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise dot between features of u and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise dot between features of u and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise dot between features of v and e if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise dot between features of v and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise dot between features of e and u if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 

Builtin message function that computes a message on an edge by performing elementwise dot between features of e and v if the features have the same shape; otherwise, it first broadcasts the features to a new shape and performs the elementwise operation. 
Reduce functions¶

Builtin reduce function that aggregates messages by sum. 

Builtin reduce function that aggregates messages by max. 

Builtin reduce function that aggregates messages by min. 

Builtin reduce function that aggregates messages by mean. 