Getting Started with TopoBench

TopoBench is a modular Python library for benchmarking and accelerating research in Topological Deep Learning (TDL). It enables training and comparison of Topological Neural Networks (TNNs) across graphs, simplicial complexes, cellular complexes, and hypergraphs.

Technical Details

For comprehensive information, see our research paper: TopoBench: A Framework for Benchmarking Topological Deep Learning

1. Environment Setup

Requirements: Python 3.11.3, conda (or Miniconda)

1. 1
   Check conda installation:

   conda --version

   If not installed, get Miniconda here.

2. 2
   Clone the repository and enter the directory:

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

3. 3
   Create and activate the environment:

   conda create -n tb python=3.11.3
   conda activate tb

4. 4
   (Optional, for GPU) Check CUDA version:

   which nvcc && nvcc --version

   Ensure CUDA matches env_setup.sh (CUDA=cpu by default). Adjust CUDA and TORCH as needed. See compatibility guide.

5. 5
   Install dependencies:

   source env_setup.sh

2. Running the Training Pipeline

After setup, train and evaluate a neural network with:

python -m topobench

3. Customizing Experiments

TopoBench uses hydra for flexible configuration. Override defaults via the command line:

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

Note

By default, the pipeline detects source/destination domains and applies a default lifting if needed.

Configuring Individual Transforms

1. Select a transform (e.g., a lifting transform).
2. Find its config path (see below):

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

3. Override the default transform:

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

4. Example:

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

Configuring Transform Groups

1. Create a config file in configs/transforms (e.g., custom_example.yaml).
2. Define the group in YAML:

   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

3. Run with the custom group:

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

Tip

Use hydra documentation for advanced configuration.

4. Reproducibility

To reproduce Table 1 from the TopoBench paper:

bash scripts/reproduce.sh

Info

Public W&B (Weights & Biases) project contains logs for all runs (updated June 11, 2024).

5. Tutorials & Further Resources

• See tutorials for adding datasets, transforms, and benchmarks.
• Many neural networks in TopoBench are from TopoModelX.
• For questions, open an issue on GitHub.