dgl

name	dgl
description	DGL (Deep Graph Library) — graph construction, message passing, GNN layers, heterogeneous graphs, and batching for fraud detection on blockchain graphs

DGL

Graph construction

import dgl
import torch

# Homogeneous graph from edge lists
src = torch.tensor([0, 1, 2, 3])
dst = torch.tensor([1, 2, 3, 0])
g = dgl.graph((src, dst))

# Add node/edge features
g.ndata["feat"] = torch.randn(g.num_nodes(), 64)
g.edata["weight"] = torch.ones(g.num_edges())

# From networkx
import networkx as nx
nx_g = nx.DiGraph()
nx_g.add_edges_from([(0, 1), (1, 2)])
g = dgl.from_networkx(nx_g)

# Add self-loops (often needed for GCN)
g = dgl.add_self_loop(g)

Heterogeneous graphs

# Ethereum: account -[sends]-> account, account -[creates]-> contract
g = dgl.heterograph({
    ("account", "sends", "account"): (src_acct, dst_acct),
    ("account", "creates", "contract"): (src_acct, dst_contract),
})

g.nodes["account"].data["feat"] = account_feats
g.edges["sends"].data["amount"] = tx_amounts

Message passing (custom MPNN)

import dgl.function as fn

# Built-in aggregation (fast, fused CUDA kernels — prefer over UDF)
g.update_all(
    fn.copy_u("h", "m"),       # message: copy src node feat
    fn.mean("m", "h_agg"),     # reduce: mean over neighbors
)
h_new = g.ndata["h_agg"]

# Edge-weighted aggregation
g.edata["e"] = edge_weights
g.update_all(
    fn.u_mul_e("h", "e", "m"),  # message: h * edge_weight
    fn.sum("m", "h_agg"),
)

# Custom UDF (slower, use only when built-ins don't cover it)
def message_fn(edges):
    return {"m": edges.src["h"] * edges.data["w"]}

def reduce_fn(nodes):
    return {"h": nodes.mailbox["m"].sum(dim=1)}

g.update_all(message_fn, reduce_fn)

Common GNN layers

from dgl.nn import GraphConv, GATConv, SAGEConv

# GCN
conv = GraphConv(in_feats=64, out_feats=128, norm="both", allow_zero_in_degree=True)
h = conv(g, g.ndata["feat"])

# GAT (multi-head attention)
gat = GATConv(64, 32, num_heads=4, feat_drop=0.1, attn_drop=0.1)
h = gat(g, g.ndata["feat"])   # shape: [N, num_heads, out_feats]
h = h.flatten(1)               # shape: [N, num_heads * out_feats]

# GraphSAGE
sage = SAGEConv(64, 128, aggregator_type="mean")
h = sage(g, g.ndata["feat"])

Mini-batch training with NodeDataLoader

from dgl.dataloading import NodeDataLoader, MultiLayerNeighborSampler

# 2-layer GNN: sample 15 neighbors at layer 2, 10 at layer 1
sampler = MultiLayerNeighborSampler([15, 10])
train_ids = torch.where(g.ndata["train_mask"])[0]

loader = NodeDataLoader(
    g, train_ids, sampler,
    batch_size=1024,
    shuffle=True,
    drop_last=False,
    num_workers=4,
)

for input_nodes, output_nodes, blocks in loader:
    # blocks: list of bipartite graphs, one per GNN layer
    h = blocks[0].srcdata["feat"]
    for i, (block, layer) in enumerate(zip(blocks, gnn_layers)):
        h = layer(block, h)
    loss = loss_fn(h, blocks[-1].dstdata["label"])

Graph batching

# Batch multiple graphs for training (e.g., transaction subgraphs)
graphs = [dgl.graph(...) for _ in range(batch_size)]
batched = dgl.batch(graphs)

# Unbatch
graphs_list = dgl.unbatch(batched)

# Readout (graph-level prediction)
import dgl
h_graph = dgl.mean_nodes(batched, "h")  # [batch_size, feat_dim]

Device handling

g = g.to("cuda")                   # move graph + all ndata/edata to GPU
g = g.to(torch.device("cuda:0"))

# In DataLoader: use device parameter (DGL >= 1.1)
loader = NodeDataLoader(..., device="cuda")

Pitfalls

• allow_zero_in_degree=True must be set for GCN/GAT when isolated nodes exist — otherwise raises an error silently giving wrong results in older versions.
• Prefer built-in dgl.function message/reduce ops over UDFs — they use fused CUDA kernels and are 2–5× faster.
• MultiLayerNeighborSampler samples in reverse layer order; blocks[0] is the input layer, blocks[-1] contains output nodes.
• Moving a graph to GPU with .to("cuda") also moves all ndata/edata tensors — don't move them separately.
• For heterogeneous graphs, use dgl.nn.HeteroGraphConv to apply different convolutions per relation type.