# geometric-intelligence/topobench architecture

> Architecture diagram of the GitHub repository geometric-intelligence/topobench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geometric-intelligence/topobench
- Repository: https://github.com/geometric-intelligence/topobench

## Overview

##### Main System Components
- Command-Line Interface & Entry Point: At the very top is the “python -m topobench” invocation that starts execution via topobench/__main__.py.
- Configuration Manager: The project leverages Hydra to manage a hierarchical configuration system (found in the configs/ directory with subdirectories for models, datasets, trainers, transforms, etc.). This component is crucial as it dynamically instantiates the chosen model, dataset, transforms, and experiment settings.
- Data Pipeline:
– Preprocessor & Transforms: The project supports multiple pre-processing steps through “data_manipulations” and “liftings” (both under configs/transforms and topobench/transforms). These components apply modifications such as feature conversion, connectivity inference, and domain transformations (e.g., graph to simplicial or graph to cell).
- Neural Network Components:
– Models & Backbones: The core of topological deep learning is implemented in topobench/nn and topobench/model. This includes the diverse set of TNN architectures (e.g., CWN, CCCN, GCN, GAT, etc.) as well as wrappers that manage training details.
- Training & Optimization:
– Trainer & Optimizer: The training loop (coordinated by topobench/run.py and related trainer configurations in configs/trainer) uses optimizer settings (found in topobench/optimizer and configs/optimizer), loss functions (in topobench/loss and configs/loss), and evaluation metrics (topobench/evaluator) to guide learning.
- Logging, Callbacks, and Evaluation:
– Logging: There are multiple logger configurations (configs/logger) which direct outputs to platforms like TensorBoard, WandB, MLflow, etc.
– Callbacks and Evaluators: The callbacks (topobench/callbacks) and evaluation modules (topobench/evaluator) monitor the training process, perform early stopping, model checkpointing, and log metrics.
- Experiment Reproducibility & Scripts:
– Scripts such as “env_setup.sh” and “scripts/reproduce.sh” handle environment setup and provide reproducible experiment pipelines.
- Testing & Documentation:
– Comprehensive unit tests (in test/) ensure integration of the various components.
– Detailed Sphinx documentation (docs/) and tutorials help users understand how to extend and use the framework.

##### Relationships and Interactions
- The CLI entry point parses command-line arguments (with overrides for model, dataset, and transforms) and passes them to Hydra.
- The Configuration Manager retrieves default and user-specified configurations for datasets, models, transforms, logging, etc.
- The Data Pipeline takes raw datasets and applies preprocessing and lifting transforms before feeding data into the model.
- The Model component (selected via configuration) processes the data and produces predictions.
- The Loss, Optimizer, and Trainer modules drive the training loop, while evaluators compute performance metrics.
- Logging and callbacks (e.g., model checkpoint, timer) operate throughout the training process for monitoring and debugging.
- The whole system is modular; each part is independently configurable and replaceable, which is reflected in the directory structure.

##### Architectural Patterns & Design Principles
- Modularity & Extensibility: A heavy emphasis on decoupling—separating data loading, model definition, training, evaluation, and transformation.
- Configuration-Driven: The use of Hydra ensures a clear separation between code and configuration, allowing experiments to be easily configured via YAML files.
- Pipeline/Flow Design: Data flows in a sequential pipeline—from input and preprocessing, to model training, to evaluation—while liftings and transforms are applied as intermediate processing layers.
- Testability: The extensive test suites (unit tests for each module in test/) indicate a design that encourages test-driven development and modular verification.

##### Technologies, Frameworks, and Libraries
- Python (3.10+ or 3.11) is the primary language.
- Hydra for configuration management.
- PyTorch (or another deep learning framework that underpins the neural network modules).
- Logging tools: TensorBoard, WandB, among others.
- Auxiliary tools for testing (pytest) and continuous integration (GitHub Actions with workflows for linting, testing, and documentation building).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry & Configuration Layer"
        CLI["python -m topobench (Entry Point)"] 
        CONFIG["Hydra Config Manager"]
    end

    CLI -->|"parses_args"| CONFIG

    subgraph "Data Ingestion & Transformation Layer"
        DATALOADER["Data Loaders"]
        PREPROCESSOR["Preprocessor & Transforms"]
    end

    CONFIG -->|"configures"| DATALOADER
    CONFIG -->|"configures"| PREPROCESSOR
    DATALOADER -->|"provides_data"| PREPROCESSOR

    subgraph "Neural Network & Training Layer"
        MODEL["Neural Network Models & Backbones"]
        TRAINER["Training & Optimization"]
    end

    PREPROCESSOR -->|"feeds_preprocessed_data"| MODEL
    MODEL -->|"triggers_training"| TRAINER

    subgraph "Evaluation & Logging Layer"
        EVALUATOR["Logging, Callbacks & Evaluation"]
    end

    TRAINER -->|"trains"| EVALUATOR
    EVALUATOR -->|"feedback"| TRAINER

    subgraph "Support & Testing"
        SCRIPTS["Experiment Scripts"]
        TESTING["Testing & Documentation"]
    end

    SCRIPTS -->|"sets_up"| CONFIG
    SCRIPTS -->|"sets_up"| TRAINER
    TESTING -->|"verifies"| MODEL
    TESTING -->|"verifies"| TRAINER

    %% Click Events
    click CLI "https://github.com/geometric-intelligence/topobench/blob/main/topobench/__main__.py"
    click CONFIG "https://github.com/geometric-intelligence/topobench/tree/main/configs/"
    click DATALOADER "https://github.com/geometric-intelligence/topobench/tree/main/topobench/data/loaders/"
    click DATALOADER "https://github.com/geometric-intelligence/topobench/tree/main/topobench/dataloader/"
    click PREPROCESSOR "https://github.com/geometric-intelligence/topobench/tree/main/topobench/data/preprocessor/"
    click PREPROCESSOR "https://github.com/geometric-intelligence/topobench/tree/main/topobench/transforms/"
    click PREPROCESSOR "https://github.com/geometric-intelligence/topobench/tree/main/configs/transforms/"
    click MODEL "https://github.com/geometric-intelligence/topobench/tree/main/topobench/model/"
    click MODEL "https://github.com/geometric-intelligence/topobench/tree/main/topobench/nn/"
    click MODEL "https://github.com/geometric-intelligence/topobench/tree/main/topobench/nn/backbones/"
    click TRAINER "https://github.com/geometric-intelligence/topobench/blob/main/topobench/run.py"
    click TRAINER "https://github.com/geometric-intelligence/topobench/tree/main/topobench/optimizer/"
    click TRAINER "https://github.com/geometric-intelligence/topobench/tree/main/configs/optimizer/"
    click TRAINER "https://github.com/geometric-intelligence/topobench/tree/main/topobench/loss/"
    click TRAINER "https://github.com/geometric-intelligence/topobench/tree/main/configs/loss/"
    click EVALUATOR "https://github.com/geometric-intelligence/topobench/tree/main/topobench/callbacks/"
    click EVALUATOR "https://github.com/geometric-intelligence/topobench/tree/main/topobench/evaluator/"
    click EVALUATOR "https://github.com/geometric-intelligence/topobench/tree/main/configs/logger/"
    click SCRIPTS "https://github.com/geometric-intelligence/topobench/blob/main/env_setup.sh"
    click SCRIPTS "https://github.com/geometric-intelligence/topobench/blob/main/scripts/reproduce.sh"
    click TESTING "https://github.com/geometric-intelligence/topobench/tree/main/test/"
    click TESTING "https://github.com/geometric-intelligence/topobench/tree/main/docs/"

    %% Styles
    classDef entryConfig fill:#f9f,stroke:#333,stroke-width:2px;
    classDef dataLayer fill:#bbf,stroke:#333,stroke-width:2px;
    classDef modelLayer fill:#afa,stroke:#333,stroke-width:2px;
    classDef trainingLayer fill:#ff9,stroke:#333,stroke-width:2px;
    classDef loggingLayer fill:#fc9,stroke:#333,stroke-width:2px;
    classDef supportLayer fill:#ddd,stroke:#333,stroke-width:2px;

    class CLI,CONFIG entryConfig;
    class DATALOADER,PREPROCESSOR dataLayer;
    class MODEL modelLayer;
    class TRAINER trainingLayer;
    class EVALUATOR loggingLayer;
    class SCRIPTS,TESTING supportLayer;
```
