DMoN (Deep Modularity Networks) Documentation

🔍 Overview

DMoN is a deep clustering model for graphs that combines graph neural networks (GNNs) with modularity optimization. It performs soft clustering by maximizing modularity while preventing collapse using a regularization term. This approach enables unsupervised, end-to-end differentiable graph clustering.

---

⚙️ Class Definition

Class Name: DMoN This PyTorch-based class implements the DMoN model using GCN layers and a soft assignment matrix.

class DMoN(nn.Module):
    def __init__(self, in_channels: int, hidden_channels: int, n_clusters: int):
        ...

---

📋 Parameters

Parameter	Type	Default	Description
in_channels	int	—	Number of input features per node
hidden_channels	int	—	Number of hidden units in GCN
n_clusters	int	—	Desired number of clusters

---

🚀 Usage Examples

from soft_clustering._dmon._dmon import DMoN
import torch

x = torch.eye(6)
edge_index = torch.tensor([[0, 1, 1, 2, 3, 4, 4, 5],
                           [1, 0, 2, 1, 4, 3, 5, 4]], dtype=torch.long)
adj = torch.zeros((6, 6))
for i, j in edge_index.t():
    adj[i, j] = 1

model = DMoN(in_channels=6, hidden_channels=8, n_clusters=2)
soft_assign = model(x, edge_index, adj)
loss = model.loss(soft_assign, adj)

---

📥 Input / 📤 Output

• Input to forward(x, edge_index, adj):

  • x (Tensor): Node feature matrix (N x F)

  • edge_index (Tensor): Edge list for graph in COO format (2 x E)

  • adj (Tensor): Dense adjacency matrix (N x N)

• Returns:

  • soft_assign (Tensor): Cluster assignment probabilities (N x K)

---

🛠️ Methods

• forward(x, edge_index, adj): Returns the soft cluster assignments.

• loss(soft_assign, adj): Computes modularity loss and collapse regularization.

---

📝 Implementation Notes

• Uses GCNConv layers from torch_geometric

• Cluster assignments computed using softmax over final GCN output

• Modularity matrix is computed using degree-normalized formula

• Collapse regularization ensures diverse cluster use

---

📚 Reference

This implementation is based on:
“Graph Clustering with Graph Neural Networks”
by Alon, Yahav, and Wolf (2021).