TopoTune

TopoBench includes TopoTune, a comprehensive framework for easily defining and training new, general TDL models on any domain using any (graph) neural network ω as a backbone. The pre-print detailing this framework is TopoTune: A Framework for Generalized Combinatorial Complex Neural Networks. In a GCCN (pictured below), the input complex is represented as an ensemble of strictly augmented Hasse graphs, one per neighborhood of the complex. Each of these Hasse graphs is processed by a sub model ω, and the outputs are rank-wise aggregated in between layers.

Generalized Combinatorial Complex Network (GCCN). The input complex $\mathcal{C}$ has neighborhoods $\mathcal{N_C}$ = { $\mathcal{N_1}$ , $\mathcal{N_2}$, $\mathcal{N_3}$ }. A. The complex is expanded into three augmented Hasse graphs $\mathcal{G_\mathcal{N_i}}$ , $i={1,2,3}$, each with features $H_\mathcal{N_i}$ represented as a colored disc. B. A GCCN layer dedicates one base architecture $\omega_\mathcal{N_i}$ C. The output of all the architectures $\omega_\mathcal{N_i}$ is aggregated rank-wise, then updated. In this example, only the complex's edge features (originally pink) are aggregated across multiple neighborhoods ($\mathcal{N_2}$ and $\mathcal{N_3}$). *

Defining and training a GCCN

To implement and train a GCCN, run the following command line with the desired choice of dataset, lifting domain (ex: cell, simplicial), PyTorch Geometric backbone model (ex: GCN, GIN, GAT, GraphSAGE) and parameters (ex. model.backbone.GNN.num_layers=2), neighborhood structure (routes), and other hyperparameters.

python -m topobench \
    dataset=graph/PROTEINS \
    dataset.split_params.data_seed=1 \
    model=cell/topotune\
    model.tune_gnn=GCN \
    model.backbone.GNN.num_layers=2 \
    model.backbone.neighborhoods=\[1-up_laplacian-0,1-down_incidence-2\] \
    model.backbone.layers=4 \
    model.feature_encoder.out_channels=32 \
    model.feature_encoder.proj_dropout=0.3 \
    model.readout.readout_name=PropagateSignalDown \
    logger.wandb.project=TopoTune_cell \
    trainer.max_epochs=1000 \
    callbacks.early_stopping.patience=50 \

To use a single augmented Hasse graph expansion, use model={domain}/topotune_onehasse instead of model={domain}/topotune.

To specify a set of neighborhoods on the complex, use a list of neighborhoods each specified as a string of the form r-{neighborhood}-k, where $k$ represents the source cell rank, and $r$ is the number of ranks up or down that the selected {neighborhood} considers. Currently, the following options for {neighborhood} are supported:

• up_laplacian, between cells of rank $k$ through $k+r$ cells.
• down_laplacian, between cells of rank $k$ through $k-r$ cells.
• hodge_laplacian, between cells of rank $k$ through both $k-r$ and $k+r$ cells.
• up_adjacency, between cells of rank $k$ through $k+r$ cells.
• down_adjacency, between cells of rank $k$ through $k-r$ cells.
• up_incidence, from rank $k$ to $k+r$.
• down_incidence, from rank $k$ to $k-r$.

The number $r$ can be omitted, in which case $r=1$ by default (e.g. up_incidence-k represents the incidence from rank $k$ to $k+1$).

Using backbone models from any package

By default, backbone models are imported from torch_geometric.nn.models. To import and specify a backbone model from any other package, such as torch.nn.Transformer or dgl.nn.GATConv, it is sufficient to 1) make sure the package is installed and 2) specify in the command line:

model.tune_gnn = {backbone_model}
model.backbone.GNN._target_={package}.{backbone_model}

Reproducing experiments

We provide scripts to reproduce experiments on a broad class of GCCNs in scripts/topotune and reproduce iterations of existing neural networks in scripts/topotune/existing_models, as previously reported in the TopoTune paper.

We invite users interested in running extensive sweeps on new GCCNs to replicate the --multirun flag in the scripts. This is a shortcut for running every possible combination of the specified parameters in a single command.