# deceptrax123/lgin architecture

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

- Interactive diagram: https://gitdiagram.com/deceptrax123/lgin
- Repository: https://github.com/deceptrax123/lgin

## Overview

##### Project Type and Purpose
- This is a Python-based research codebase implementing the “Lorentzian Graph Isomorphic Network” (LGIN), a graph neural network operating in Lorentzian hyperbolic space. It provides:
- Data download and preprocessing scripts
- Manifold abstractions (Euclidean & Lorentzian)
- Custom hyperbolic operations and GNN layer
- Model definitions, training pipelines, and statistical analysis

##### File Structure Analysis
- Top-level scripts:
- train.py / train_regression.py – entry points for classification and regression experiments
- data/download.py – dataset download and preparation
- Core modules:
- manifolds/ – implements Euclidean and Lorentzian manifold operations
- layers/ – defines the LGIN layer and low-level Lorentz operations
- models/model.py – assembles the GNN architecture using manifold and layer modules
- optimizers/radam.py – custom optimizer
- metrics.py – evaluation metrics
- utils/ – math utilities
- model_config.py – hyperparameter and curvature settings
- Experiment analysis:
- statistical_tests/ – ablation studies, t-tests, and plotting

##### Key README Insights
- Implements a new update rule preserving the Lorentzian metric tensor
- Demonstrates discriminative power comparable to WL tests
- Dependencies: PyTorch, torch-geometric, numpy, scipy, matplotlib, wandb, etc.

a. Main Components
1. Data Layer
– External dataset repositories (e.g., MUTAG, Proteins, etc.)
– data/download.py
2. Preprocessing & DataLoader
– PyG Data objects
– Batch preparation
3. Model Layer
– Manifolds module (Euclidean / Lorentzian)
– Lorentz operations (layers/lorentz_ops.py)
– LGIN layer (layers/lgin_layer.py)
– Graph network assembly (models/model.py)
4. Training Pipeline
– train.py / train_regression.py orchestrating epochs, loss, optimizer (radam)
– model_config.py controlling hyperparameters and curvature
– Logging to wandb or console
5. Evaluation & Analysis
– metrics.py for accuracy / regression metrics
– statistical_tests/ for ablation, t-tests, and plotting results
b. Relationships & Data Flow
1. Data sources → data/download.py → Preprocessing
2. Preprocessed Data → PyG DataLoader → Model forward pass
3. Model forward/backward → Optimizer (radam) → Parameter updates
4. Training/Evaluation loop → metrics → Logging (wandb, files)
5. Experiment outputs → statistical_tests → Plots/Reports
c. Architectural Patterns & Principles
– Modular separation of manifold math vs. high-level GNN logic
– Layer/plugin pattern for custom GNN layers
– Config-driven design via model_config.py and .env files for dataset paths
– Clear separation of training vs. analysis code
d. Key Technologies & Frameworks
– Python 3.10+
– PyTorch & torch-geometric
– numpy, scipy
– python-dotenv for environment config
– matplotlib for plotting, wandb for experiment tracking

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawData(("Raw Graph Datasets")):::external
        Download[/download.py/]:::script
        DataLoader["PyG DataLoader"]:::processing
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        subgraph "Manifold Abstractions"
            direction TB
            BaseManifold["base.py"]:::manifold
            EucManifold["euclidean.py"]:::manifold
            LorentzManifold["lorentzian.py"]:::manifold
        end
        LorentzOps["lorentz_ops.py"]:::layer
        LGINLayer["lgin_layer.py"]:::layer
        ModelDef["model.py"]:::model
    end

    %% Training Layer
    subgraph "Training Layer"
        direction TB
        TrainCls[/train.py/]:::script
        TrainReg[/train_regression.py/]:::script
        Config["model_config.py"]:::script
        Optimizer["radam.py"]:::optimizer
        Wandb((wandb)):::external
    end

    %% Analysis Layer
    subgraph "Analysis Layer"
        direction TB
        Metrics["metrics.py"]:::script
        Ablation["ablation_study.py"]:::analysis
        AblationPoints["ablation_study_points.py"]:::analysis
        TTest["t_test.py"]:::analysis
        Plots(("plots/")):::analysis
    end

    %% Connections
    RawData -->|downloads via| Download
    Download -->|prepares data| DataLoader
    DataLoader -->|batches data| ModelDef
    BaseManifold -->|provides| ModelDef
    EucManifold -->|provides| ModelDef
    LorentzManifold -->|provides| ModelDef
    LorentzOps -->|used in| ModelDef
    LGINLayer -->|used in| ModelDef
    ModelDef -->|forward/backward| Optimizer
    Config -->|sets params| TrainCls
    Config -->|sets params| TrainReg
    TrainCls -->|runs training| ModelDef
    TrainReg -->|runs training| ModelDef
    Optimizer -->|updates params| ModelDef
    ModelDef -->|evaluates| Metrics
    Metrics -->|logs to| Wandb
    Metrics -->|outputs results| Ablation
    Ablation -->|generates| Plots
    AblationPoints -->|generates| Plots
    TTest -->|analyses results| Plots

    %% Click Events
    click Download "https://github.com/deceptrax123/lgin/blob/Main/data/download.py"
    click BaseManifold "https://github.com/deceptrax123/lgin/blob/Main/manifolds/base.py"
    click EucManifold "https://github.com/deceptrax123/lgin/blob/Main/manifolds/euclidean.py"
    click LorentzManifold "https://github.com/deceptrax123/lgin/blob/Main/manifolds/lorentzian.py"
    click LorentzOps "https://github.com/deceptrax123/lgin/blob/Main/layers/lorentz_ops.py"
    click LGINLayer "https://github.com/deceptrax123/lgin/blob/Main/layers/lgin_layer.py"
    click ModelDef "https://github.com/deceptrax123/lgin/blob/Main/models/model.py"
    click Optimizer "https://github.com/deceptrax123/lgin/blob/Main/optimizers/radam.py"
    click TrainCls "https://github.com/deceptrax123/lgin/blob/Main/train.py"
    click TrainReg "https://github.com/deceptrax123/lgin/blob/Main/train_regression.py"
    click Config "https://github.com/deceptrax123/lgin/blob/Main/model_config.py"
    click Metrics "https://github.com/deceptrax123/lgin/blob/Main/metrics.py"
    click Ablation "https://github.com/deceptrax123/lgin/blob/Main/statistical_tests/ablation_study.py"
    click AblationPoints "https://github.com/deceptrax123/lgin/blob/Main/statistical_tests/ablation_study_points.py"
    click TTest "https://github.com/deceptrax123/lgin/blob/Main/statistical_tests/t_test.py"
    click Plots "https://github.com/deceptrax123/lgin/tree/Main/statistical_tests/plots/"

    %% Styles
    classDef external fill:#FDEBD0,stroke:#D98880
    classDef data fill:#D6EAF8,stroke:#2874A6
    classDef processing fill:#FCF3CF,stroke:#B7950B
    classDef manifold fill:#D5F5E3,stroke:#229954
    classDef layer fill:#F9E79F,stroke:#B7950B
    classDef model fill:#E8DAEF,stroke:#8E44AD
    classDef optimizer fill:#FADBD8,stroke:#C0392B
    classDef script fill:#E5E7E9,stroke:#566573
    classDef analysis fill:#FDEDEC,stroke:#78281F
```
