README.md

A Comprehensive Benchmark Suite for Topological Deep Learning

Assess how your model compares against state-of-the-art topological neural networks.

Overview • Get Started • Tutorials • Neural Networks • Liftings and Transforms • Datasets • References

🏆 2026 Topological Deep Learning Challenge is now live! Check out guidelines and full details on the challenge website.

:pushpin: Overview

TopoBench (TB) is a modular Python library designed to standardize benchmarking and accelerate research in Topological Deep Learning (TDL). In particular, TB allows training and comparing the performances of all sorts of Topological Neural Networks (TNNs) across the different topological domains, where by topological domain we refer to a graph, a simplicial complex, a cellular complex, or a hypergraph. For detailed information, please refer to the TopoBench: A Framework for Benchmarking Topological Deep Learning paper.

The main pipeline trains and evaluates a wide range of state-of-the-art TNNs and Graph Neural Networks (GNNs) (see :gear: Neural Networks) on numerous and varied datasets and benchmark tasks (see :books: Datasets ). Additionally, the library offers the ability to transform, i.e. lift, each dataset from one topological domain to another (see :rocket: Liftings and Transforms), enabling for the first time an exhaustive inter-domain comparison of TNNs.

:jigsaw: Get Started

🚀 Quick Install (Recommended)

TopoBench now uses uv, an extremely fast Python package manager and resolver. This allows for nearly instantaneous environment setup and reproducible builds.

1. Install uv

2. Clone and Navigate:

   git clone git@github.com:geometric-intelligence/topobench.git
   cd TopoBench
   

3. Initialize Environment: Use our centralized setup script to handle Python 3.11 virtualization and specialized hardware (CUDA) mapping.

   # Usage: source uv_env_setup.sh [cpu|cu118|cu121]
   source uv_env_setup.sh cpu
   

   This script performs the following:

   • Creates a .venv using Python 3.11.
   • Dynamically configures pyproject.toml to point to the correct PyTorch and PyG (PyTorch Geometric) wheels for your platform.
   • Generates a precise uv.lock file and syncs all dependencies.

🛠️ Manual Environment Setup

If you prefer to manage the environment manually or are integrating into an existing workflow:

# Create a virtual environment with strict versioning
uv venv --python 3.11
source .venv/bin/activate

# Sync dependencies including all extras (dev, test, and doc)
uv sync --all-extras

🚄 Run Training Pipeline Once the environment is active, you can launch the TopoBench pipeline:

# Using the activated virtual environment
python -m topobench

# Or execute directly via uv without manual activation
uv run python -m topobench

✅ Verify Installation You can verify that the correct versions of Torch and CUDA are detected by running:

python -c "import torch; print(f'Torch: {torch.__version__} | CUDA: {torch.version.cuda}')"

Customizing Experiment Configuration

Thanks to hydra implementation, one can easily override the default experiment configuration through the command line. For instance, the model and dataset can be selected as:

python -m topobench model=cell/cwn dataset=graph/MUTAG

Remark: By default, our pipeline identifies the source and destination topological domains, and applies a default lifting between them if required.

Transforms allow you to modify your data before processing. There are two main ways to configure transforms: individual transforms and transform groups.

├── configs
│ ├── data_manipulations
│ ├── transforms
│ │ └── liftings
│ │   ├── graph2cell
│ │   ├── graph2hypergraph
│ │   └── graph2simplicial

python -m topobench model=<model_type>/<model_name> dataset=<data_type>/<dataset_name> transforms=[<transform_path>/<transform_name>]

python -m topobench model=cell/cwn dataset=graph/MUTAG transforms=[liftings/graph2cell/discrete_configuration_complex]

defaults:
- data_manipulations@data_transform_1: identity
- data_manipulations@data_transform_2: node_degrees
- data_manipulations@data_transform_3: one_hot_node_degree_features
- liftings/graph2cell@graph2cell_lifting: cycle

python -m topobench model=cell/cwn dataset=graph/ZINC transforms=custom_example

Additional Notes

• Automatic Lifting: By default, our pipeline identifies the source and destination topological domains and applies a default lifting between them if required.
• Fine-Grained Configuration: The same CLI override mechanism applies when modifying finer configurations within a CONFIG GROUP.
  Please refer to the official hydra documentation for further details.

:bike: Experiments Reproducibility

The scripts/ folder contains all the scripts needed to reproduce the experiments from our works. Each subfolder corresponds to one paper:

• TopoBench: A Framework for Benchmarking Topological Deep Learning — scripts/topobench/
• TopoTune: A Framework for Generalized Combinatorial Complex Neural Networks — scripts/topotune/
• HOPSE: Higher-Order Positional and Structural Encodings — scripts/hopse/

For example, to reproduce Table 1 from the TopoBench paper:

bash scripts/topobench/reproduce.sh

:anchor: Tutorials

Explore our tutorials for further details on how to add new datasets, transforms/liftings, and benchmark tasks.

:gear: Neural Networks

We list the neural networks trained and evaluated by TopoBench, organized by the topological domain over which they operate: graph, simplicial complex, cellular complex or hypergraph. Many of these neural networks were originally implemented in TopoModelX.

Pointclouds

Graphs

Simplicial Complexes

Cellular Complexes

Hypergraphs

Combinatorial Complexes

Remark: TopoBench includes TopoTune, a comprehensive framework for easily designing new, general TDL models on any domain using any (graph) neural network as a backbone. Please check out the extended TopoTune wiki page for further details on how to leverage this framework to define and train customized topological neural network architectures.

Non-relational Models

Remark: Note that MLP only works in single-graph transductive settings or with datasets where all graphs have the same number of nodes.

:rocket: Liftings and Transforms

We list the liftings used in TopoBench to transform datasets. Here, a lifting refers to a function that transforms a dataset defined on a topological domain (e.g., on a graph) into the same dataset but supported on a different topological domain (e.g., on a simplicial complex).

Structural Liftings

The structural lifting is responsible for the transformation of the underlying relationships or elements of the data. For instance, it might determine how nodes and edges in a graph are mapped into triangles and tetrahedra in a simplicial complex. This structural transformation can be further categorized into connectivity-based, where the mapping relies solely on the existing connections within the data, and feature-based, where the data's inherent properties or features guide the new structure.

We enumerate below the structural liftings currently implemented in TopoBench; please check out the provided description links for further details.

Remark:: Most of these liftings are adaptations of winner submissions of the ICML TDL Challenge 2024 (paper | repo); see the Structural Liftings wiki for a complete list of compatible liftings.

Graph to Simplicial Complex

Graph to Cell Complex

Graph to Hypergraph

Pointcloud to Simplicial

Pointcloud to Hypergraph

Simplicial to Combinatorial

Hypergraph to Combinatorial

Feature Liftings

Feature liftings address the transfer of data attributes or features during mapping, ensuring that the properties associated with the data elements are consistently preserved in the new representation.

Data Transformations

Specially useful in pre-processing steps, these are the general data manipulations currently implemented in TopoBench:

:books: Datasets

Graph

Remark: GraphUniverse is a synthetic graph generator for community-structured data, enabling control over graph properties like homophily, feature-signal and degree structure. Live Demo: Demo. Package release: PyPi. GitHub repository: Repo.

Simplicial

Hypergraph

:mag: References

To learn more about TopoBench, we invite you to read the paper:

@article{
telyatnikov2025topobench,
title={TopoBench: A Framework for Benchmarking Topological Deep Learning},
author={Lev Telyatnikov and Guillermo Bernardez and Marco Montagna and Mustafa Hajij and Martin Carrasco and Pavlo Vasylenko and Mathilde Papillon and Ghada Zamzmi and Michael T Schaub and Jonas Verhellen and Pavel Snopov and Bertran Miquel-Oliver and Manel Gil-Sorribes and Alexis Molina and VICTOR GUALLAR and Theodore Long and Julian Suk and Patryk Rygiel and Alexander V Nikitin and Giordan Escalona and Michael Banf and Dominik Filipiak and Liliya Imasheva and Max Schattauer and Alvaro L. Martinez and Halley Fritze and Marissa Masden and Valentina S{\'a}nchez and Manuel Lecha and Andrea Cavallo and Claudio Battiloro and Matthew Piekenbrock and Mauricio Tec and George Dasoulas and Nina Miolane and Simone Scardapane and Theodore Papamarkou},
journal={Journal of Data-centric Machine Learning Research},
issn={XXXX-XXXX},
year={2025},
url={https://openreview.net/forum?id=07sTzyEVtY},
note={}
}

If you find TopoBench useful, we would appreciate if you cite us!

:mouse: Additional Details

├── configs                   <- Hydra configs
│   ├── callbacks                <- Callbacks configs
│   ├── dataset                  <- Dataset configs
│   │   ├── graph                    <- Graph dataset configs
│   │   ├── hypergraph               <- Hypergraph dataset configs
│   │   └── simplicial               <- Simplicial dataset configs
│   ├── debug                    <- Debugging configs
│   ├── evaluator                <- Evaluator configs
│   ├── experiment               <- Experiment configs
│   ├── extras                   <- Extra utilities configs
│   ├── hparams_search           <- Hyperparameter search configs
│   ├── hydra                    <- Hydra configs
│   ├── local                    <- Local configs
│   ├── logger                   <- Logger configs
│   ├── loss                     <- Loss function configs
│   ├── model                    <- Model configs
│   │   ├── cell                     <- Cell model configs
│   │   ├── graph                    <- Graph model configs
│   │   ├── hypergraph               <- Hypergraph model configs
│   │   └── simplicial               <- Simplicial model configs
│   ├── optimizer                <- Optimizer configs
│   ├── paths                    <- Project paths configs
│   ├── scheduler                <- Scheduler configs
│   ├── trainer                  <- Trainer configs
│   ├── transforms               <- Data transformation configs
│   │   ├── data_manipulations       <- Data manipulation transforms
│   │   ├── dataset_defaults         <- Default dataset transforms
│   │   ├── feature_liftings         <- Feature lifting transforms
│   │   └── liftings                 <- Lifting transforms
│   │       ├── graph2cell               <- Graph to cell lifting transforms
│   │       ├── graph2hypergraph         <- Graph to hypergraph lifting transforms
│   │       ├── graph2simplicial         <- Graph to simplicial lifting transforms
│   │       ├── graph2cell_default.yaml  <- Default graph to cell lifting config
│   │       ├── graph2hypergraph_default.yaml <- Default graph to hypergraph lifting config
│   │       ├── graph2simplicial_default.yaml <- Default graph to simplicial lifting config
│   │       ├── no_lifting.yaml           <- No lifting config
│   │       ├── custom_example.yaml       <- Custom example transform config
│   │       └── no_transform.yaml         <- No transform config
│   ├── wandb_sweep              <- Weights & Biases sweep configs
│   │
│   ├── __init__.py              <- Init file for configs module
│   └── run.yaml               <- Main config for training

📢 Get in Touch!

We are always open to collaborations and discussions on TDL research.
Feel free to reach out via email if you want to collaborate, do your thesis with our team, or open a discussion for various opportunities.

📧 Contact Email: topological.intelligence@gmail.com
▶️ YouTube Channel: Topological Intelligence