Release version

News

2025-09-01 -> v0.9.5 is now available! Fix some bugs and migrated to UV package manager with PEP 621 format!
2025-09-01 -> v0.9.5 正式发布！修复了若干bug，并迁移到UV包管理器，采用PEP 621格式！
2024-01-31 -> v0.9.4 is now available! Fix some bugs and more datasets are included!
2024-01-31 -> v0.9.4 正式发布！修复了若干bug，包含更多数据集！
2022-12-28 -> v0.9.3 is now available! More datasets and operations of hypergraph are included!
2022-12-28 -> v0.9.3 正式发布！包含更多数据集和超图操作！
2022-09-25 -> v0.9.2 is now available! More datasets, SOTA models, and visualizations are included!
2022-09-25 -> v0.9.2 正式发布！包含更多数据集、最新模型和可视化功能！
2022-08-25 -> DHG's first version v0.9.1 is now available!
2022-08-25 -> DHG的第一个版本 v0.9.1 正式发布！

DHG (DeepHypergraph) is a deep learning library built upon PyTorch for learning with both Graph Neural Networks and Hypergraph Neural Networks. It is a general framework that supports both low-order and high-order message passing like from vertex to vertex, from vertex in one domain to vertex in another domain, from vertex to hyperedge, from hyperedge to vertex, from vertex set to vertex set.

It supports a wide variety of structures like low-order structures (graph, directed graph, bipartite graph, etc.), high-order structures (hypergraph, etc.). Various spectral-based operations (like Laplacian-based smoothing) and spatial-based operations (like message psssing from domain to domain) are integrated inside different structures. It provides multiple common metrics for performance evaluation on different tasks. Many state-of-the-art models are implemented and can be easily used for research. We also provide various visualization tools for both low-order structures and high-order structures.

In addition, DHG's dhg.experiments module (that implements Auto-ML upon Optuna) can help you automatically tune the hyper-parameters of your models in training and easily outperforms the state-of-the-art models.

Framework of DHG Structures

Framework of DHG Function Library

Hightlights
Installation
Dependencies
Quick Start
Examples
Datasets
Metrics
Implemented Models

Highlights

Support High-Order Message Passing on Structure: DHG supports pair-wise message passing on the graph structure and beyond-pair-wise message passing on the hypergraph structure.
Shared Ecosystem with Pytorch Framework: DHG is built upon Pytorch, and any Pytorch-based models can be integrated into DHG. If you are familiar with Pytorch, you can easily use DHG.
Powerful API for Designing GNNs and HGNNs: DHG provides various Laplacian matrices and message passing functions to help build your spectral/spatial-based models, respectively.
Visualization of Graphs and Hypergraphs DHG provides a powerful visualization tool for graph and hypergraph. You can easily visualize the structure of your graph and hypergraph.
Bridge the Gap between Graphs and Hypergraphs: DHG provides functions to build hypergraph from graph and build graph from hypergraph. Maybe promoting the graph to hypergraph can exploit those potential high-order connections and improve the performance of your model.
Attach Spectral/Spatial-Based Operations to Structure: In DHG, those Laplacian matrices and message passing functions are attached to the graph/hypergraph structure. As soon as you build a structure with DHG, those functions will be ready to be used in the process of building your model.
Comprehensive, Flexible, and Convenience: DHG provides random graph/hypergraph generators, various state-of-the-art graph/hypergraph convolutional layers and models, various public graph/hypergraph datasets, and various evaluation metrics.
Support Tuning Structure and Model with Auto-ML: The Optuna library endows DHG with the Auto-ML ability. DHG supports automatically searching the optimal configurations for the construction of graph/hypergraph structure and the optimal hyper-parameters for your model and training.

Installation

Current, the stable version of DHG is 0.9.5. You can install it with pip as follows:

pip install dhg

You can also try the nightly version (0.9.6) of DHG library with pip as follows:

pip install git+https://github.com/iMoonLab/DeepHypergraph.git

Nightly version is the development version of DHG. It may include the lastest SOTA methods and datasets, but it can also be unstable and not fully tested. If you find any bugs, please report it to us in GitHub Issues.

Dependencies

DHG requires the following dependencies:

Python >= 3.8
PyTorch >= 1.12.1, < 2.0
scipy >= 1.8
matplotlib >= 3.7.0
numpy
scikit-learn
optuna
requests

For visualization features, matplotlib 3.7.0 or higher is required to properly render 3D plots.

Quick Start

Visualization

You can draw the graph, hypergraph, directed graph, and bipartite graph with DHG's visualization tool. More details see the Tutorial

Visualization of graph and hypergraph

import matplotlib.pyplot as plt
import dhg
# draw a graph
g = dhg.random.graph_Gnm(10, 12)
g.draw()
# draw a hypergraph
hg = dhg.random.hypergraph_Gnm(10, 8)
hg.draw()
# show figures
plt.show()

Visualization of directed graph and bipartite graph

import matplotlib.pyplot as plt
import dhg
# draw a directed graph
g = dhg.random.digraph_Gnm(12, 18)
g.draw()
# draw a bipartite graph
g = dhg.random.bigraph_Gnm(30, 40, 20)
g.draw()
# show figures
plt.show()

Learning on Low-Order Structures

On graph structures, you can smooth a given vertex features with GCN's Laplacian matrix by:

import torch
import dhg
g = dhg.random.graph_Gnm(5, 8)
X = torch.rand(5, 2)
X_ = g.smoothing_with_GCN(X)

On graph structures, you can pass messages from vertex to vertex with mean aggregation by:

import torch
import dhg
g = dhg.random.graph_Gnm(5, 8)
X = torch.rand(5, 2)
X_ = g.v2v(X, aggr="mean")

On directed graph structures, you can pass messages from vertex to vertex with mean aggregation by:

import torch
import dhg
g = dhg.random.digraph_Gnm(5, 8)
X = torch.rand(5, 2)
X_ = g.v2v(X, aggr="mean")

On bipartite graph structures, you can smoothing vertex features with GCN's Laplacian matrix by:

import torch
import dhg
g = dhg.random.bigraph_Gnm(3, 5, 8)
X_u, X_v = torch.rand(3, 2), torch.rand(5, 2)
X = torch.cat([X_u, X_v], dim=0)
X_ = g.smoothing_with_GCN(X, aggr="mean")

On bipartite graph structures, you can pass messages from vertex in U set to vertex in V set by mean aggregation by:

import torch
import dhg
g = dhg.random.bigraph_Gnm(3, 5, 8)
X_u, X_v = torch.rand(3, 2), torch.rand(5, 2)
X_u_ = g.v2u(X_v, aggr="mean")
X_v_ = g.u2v(X_u, aggr="mean")

Learning on High-Order Structures

On hypergraph structures, you can smooth a given vertex features with HGNN's Laplacian matrix by:

import torch
import dhg
hg = dhg.random.hypergraph_Gnm(5, 4)
X = torch.rand(5, 2)
X_ = hg.smoothing_with_HGNN(X)

On hypergraph structures, you can pass messages from vertex to hyperedge with mean aggregation by:

import torch
import dhg
hg = dhg.random.hypergraph_Gnm(5, 4)
X = torch.rand(5, 2)
Y_ = hg.v2e(X, aggr="mean")

Then, you can pass messages from hyperedge to vertex with mean aggregation by:

X_ = hg.e2v(Y_, aggr="mean")

Or, you can pass messages from vertex set to vertex set with mean aggregation by:

X_ = hg.v2v(X, aggr="mean")

Examples

Building the Convolution Layer of GCN

class GCNConv(nn.Module):
    def __init__(self,):
        super().__init__()
        ...
        self.reset_parameters()

    def forward(self, X: torch.T

DeepHypergraph

Install / Use

README