How deceptrax123/lgin works
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