TopoModelX (TMX)

The TopoModelX package is organized into three primary modules that handle different aspects of topological modeling:

• base: Implements core mathematical concepts, specifically the fundamental mechanics of message passing.
• nn: Contains neural network layers, which are categorized by their topological domains.
• utils: Provides utility functions, such as operations for computing with sparse tensors.

The nn module in TopoModelX provides neural network components specifically designed for topological data structures. It is organized into three primary submodules based on the type of topological structure being modeled:

1. cell: Components for cell complexes.
2. hypergraph: Components for hypergraph-based neural networks.
3. simplicial: Components for simplicial complex-based neural networks.

Users should select the submodule that corresponds to the mathematical structure of their input data (e.g., use simplicial for simplicial complexes or hypergraph for hypergraphs).

The Cell base class in TopoModelX is implemented through six primary classes that form the core of the neural network cell architecture. These classes are categorized into layers and their corresponding functional units:

• CAN: Can_Layer and Can
• CCXN: CCXN_Layer and CCXN
• CWN: CWN_Layer and CWN

When implementing a {Name of model}Layer, follow these structural and technical guidelines:

• Domain Placement: Store the file in topomodelx/nn/simplicial, topomodelx/nn/cell, topomodelx/nn/hypergraph, or topomodelx/nn/combinatorial based on the model's domain.
• Primitives: Use TopoModelX computational primitives. If you must modify topomodelx/base to add new primitives, you must provide unit tests for every new function added.
• Logic: One layer should be equivalent to the message passing depicted in the tensor diagram representation for the model.
• Testing: Use pytest (not unittest) for all unit tests.

The Base class in TopoModelX is a foundational structure composed of three primary functional layers used to build topological models:

1. Aggregation: Defines the message passing layer, determining how information is combined.
2. Conv: Responsible for building the message passing neighborhood structure.
3. Message Passing: The core class defining the message passing structure itself.

You can install the core topomodelx package using pip. Note that you must also install torch and specific PyTorch geometric dependencies (torch-scatter, torch-sparse, and torch-cluster) compatible with your CUDA version to ensure full functionality.

pip install topomodelx

# Example for CUDA 11.3 (replace ${CUDA} with cpu, cu102, cu113, or cu115)
pip install torch==2.0.1 --extra-index-url https://download.pytorch.org/whl/cu113
pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.1+cu113.html
pip install torch-cluster -f https://data.pyg.org/whl/torch-2.0.0+cu113.html

When creating the {name_of_model}_train.ipynb tutorial, use the following patterns for data preparation:

For models requiring features on faces or rank-2 neighborhood matrices:

Use TopoNetX to load:

• shrec16: Suitable for complex-level classification.
• Karate Club: Suitable for node-level classification.

For models requiring only node/edge features and rank-0/1 neighborhood matrices:

Use TopoNetX or Torch Geometric to load benchmark graph datasets.

Lifting to Topological Domains:

After loading the graph dataset, you must lift it from the graph domain to the chosen topological domain (hypergraph, simplicial complex, cell complex, or combinatorial complex) using TopoNetX.

TopoModelX provides specialized tutorials for implementing Topological Neural Networks (TNNs) across different mathematical structures. You can find detailed notebooks for the following domains:

• Cellular Complexes: Tutorials located in ../notebooks/cell/.
• Hypergraphs: Tutorials located in ../notebooks/hypergraph/.
• Simplicial Complexes: Tutorials located in ../notebooks/simplicial/.

Each tutorial typically follows a workflow of loading a dataset, preparing Laplacians and features, defining the network architecture, and performing forward passes.

To contribute to TMX, it is recommended to use Python 3.12 or later. Follow these steps to set up a local development environment:

1. Create and activate a conda environment:

   conda create -n tmx python=3.12
   conda activate tmx

2. Clone the repository and install in editable mode:

   git clone git@github.com:pyt-team/TopoModelX.git
   cd TopoModelX
   pip install -e '.[all]'

   Note: On Windows, use pip install -e .[all] without quotes.
3. Install PyTorch and its dependencies (torch-scatter, torch-sparse, torch-cluster) as described in the installation guide.
4. Run the test suite using pytest and install pre-commit hooks with pre-commit install.