How liyongkang123/h3gnn works
Project Type and Purpose
• This is a research-oriented machine learning project implementing “Heterogeneous Hyperbolic Hypergraph Neural Network” for friend recommendation in location-based social networks.
• It is not a full-stack web application but a data-processing + model-training pipeline, with preprocessed datasets, data-preprocessing notebooks, model definitions, and training scripts.
High-Level Components
a. Data Sources
• Raw Gowalla CSVs under data_preprocess/yongliu_gowalla_data
b. Data Preprocessing Layer
• Notebook scripts to split by city, build hypergraph, build multigraph (data_preprocess/*.ipynb)
• Outputs: pickled hypergraph/multigraph files in data/<CITY>
c. Configuration
• config.py holds all hyperparameters and path settings
d. Model Definition
• manifold/ folder: EuclideanManifold.py, PoincareManifold.py, manifold_utils.py
• model_Euclidean.py and model_Poincare.py define the two variants
e. Training and Evaluation
• train_hyperbolic.py orchestrates loading data, instantiating the model, training loop, metrics logging
• prepare.py handles dataset loading and graph construction for DGL or PyG
• utils.py contains helper functions (logging, evaluation metrics)
• ablation_study_models.py for running additional comparative experiments
f. Output Artifacts
• Trained model checkpoints, logs, recommendation results
Component Relationships & Data Flow
• Raw data → split_data_into_city.ipynb → city-specific raw files
• city raw files → build_hypergraph.ipynb & build_multigraph.ipynb → pickled graph tensors in data/<CITY>
• train_hyperbolic.py reads config.py, loads pickled data via prepare.py → uses manifold/ utilities to embed nodes → passes embeddings and graph structure to model_* → training loop → utils logs results → checkpoints saved
• ablation_study_models.py imports model definitions and repeats training/evaluation
Architectural Patterns & Design Principles
• Pipeline pattern for sequential data transformation
• Separation of concerns: data preparation, model definition, training, utilities
• Pluggable manifold implementations (Euclidean vs Poincare) via factory pattern in config & train_hyperbolic.py
• Extensible hypergraph/multigraph construction for future graph types
Relevant Technologies
• Python 3.10
• PyTorch for tensor operations and optimization
• DGL and PyG for graph and hypergraph data structures and message passing
• Standard scientific stack: numpy, pandas
• Jupyter notebooks for interactive data preprocessing
• Data Layer (raw → processed)
• Preprocessing Layer
• Configuration Layer
• Modeling Layer
• Training & Evaluation Layer
• Output Layer
• Raw CSVs → Preprocessing notebooks → Pickled graph data
• Pickled data + config.py → prepare.py → manifold utilities → model definitions → train_hyperbolic.py → checkpoints & logs
• ablation_study_models.py parallel to train_hyperbolic.py, pointing to model definitions and utils