Homological Neural Networks (HNN)

This repository contains the implementation of Homological Neural Networks (HNN), a neural network architecture that leverages topological information in data through clique structures. HNNs use sparse connectivity patterns derived from topological analysis to create parameter-efficient models.

Repository Structure

GhtHubHNN/
├── hnn_core/                          # Core HNN implementation
│   ├── fastMFCF/                     # Fast MFCF implementation
│   └── hnn_builder.py                # HNN model builder
└── examples/                         # Example usage and benchmarks
    ├── bench_utils/                  # Utility functions for benchmarking
    ├── benchmark_datasets/           # Classic ML datasets for testing
    ├── compare_modles_with_hnn.py    # Main benchmark script
    ├── generate_data.py              # Synthetic data generation
    └── run_benchmark_suite.py        # Automated benchmark runner

Core Components

hnn_core

• hnn_builder.py: Contains the core HNN implementation with sparse layer support
• fastMFCF/: Implementation of Fast Maximum Filtered Clique Forest algorithm for topology extraction

examples

• compare_modles_with_hnn.py: Main script to compare HNN variants with baseline models
• generate_data.py: Generate synthetic data with planted simplicial structure
• benchmark_datasets/: Collection of classic ML datasets (Australian, Ionosphere, Sonar, etc.)
• bench_utils/: Utility functions for benchmarking, data loading, and visualization

Model Variants

The implementation includes three HNN topology variants:

1. MST (Minimum Spanning Tree): 2-cliques, highly sparse connectivity
2. OPTT (Optimal Transport on Trees): 3-cliques, intermediate sparsity
3. TMFG (Triangulated Maximally Filtered Graph): 4-cliques, moderate sparsity

Each variant is compared against:

• RandomHNN: Same topology but randomized connections
• DenseMLP: Standard fully-connected neural network
• LogisticRegression: Linear baseline
• RandomForest: Tree-based baseline

Usage

Synthetic Data Experiments

To run a benchmark comparison on synthetic data:

python examples/compare_modles_with_hnn.py --seed 123

For multiple runs with different seeds:

python examples/compare_modles_with_hnn.py --seeds 1,2,3,4,5

Real Dataset Benchmarks

To run benchmarks on real datasets:

python examples/compare_modles_with_hnn.py --mode benchmark --dataset ionosphere --seed 42

To run multiple datasets automatically:

python examples/run_benchmark_suite.py

Output Organization

Results are organized in a structured directory format:

Synthetic Data:

• results_synthetic/seed123/: Results in JSON format
• curves_synthetic/seed123/: Learning curves and network visualizations

Benchmark Data:

• results_benchmarks/dataset_seed123/: Results for real datasets
• curves_benchmarks/dataset_seed123/: Learning curves and network visualizations

Key Features

Parameter Efficiency

HNNs demonstrate significant parameter reduction compared to dense networks:

• 6-35x fewer parameters than equivalent dense MLPs
• Maintains competitive or superior performance
• Topology-aware sparse connectivity

Benchmark Datasets

Includes 6 classic ML datasets:

• Australian Credit Approval
• Ionosphere
• Sonar
• Heart Disease (Statlog)
• Spambase
• Diabetes Risk Prediction

Comprehensive Analysis

• Learning curve visualization
• Network topology visualization
• Performance metrics (Accuracy, MCC)
• Parameter count analysis
• Training time comparison

Installation

1. Clone the repository:

git clone https://github.com/FinancialComputingUCL/homological-neural-networks.git
cd homological-neural-networks

2. Install dependencies:

pip install -r requirements.txt

3. Run a quick test:

python examples/compare_modles_with_hnn.py --seed 42

Dependencies

• PyTorch (>=2.0.0)
• NumPy (>=1.24.0)
• Matplotlib (>=3.7.0)
• NetworkX (>=3.1)
• Scikit-learn (>=1.3.0)
• SciPy (>=1.10.0)
• Pandas (>=2.0.0)
• Seaborn (>=0.12.0)

Citation

If you use this code in your research, please cite:

@misc{hnn2024,
  title={Homological Neural Networks: Topology-Aware Sparse Neural Architectures},
  author={FinancialComputingUCL},
  year={2024},
  url={https://github.com/FinancialComputingUCL/homological-neural-networks}
}