# liyongkang123/h3gnn architecture

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

- Interactive diagram: https://gitdiagram.com/liyongkang123/h3gnn
- Repository: https://github.com/liyongkang123/h3gnn

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        RawCSVs[(Raw Gowalla CSVs)]:::data
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        SplitNotebook["split_data_into_city.ipynb"]:::preproc
        BuildHyper["bulit_hypergraph.ipynb"]:::preproc
        BuildMulti["bulit_multigraph.ipynb"]:::preproc
        PickledData[(Pickled Graph Data)]:::data
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["config.py"]:::config
    end

    %% Modeling Layer
    subgraph "Modeling Layer"
        Prepare["prepare.py"]:::modeling
        ManifoldUtils["manifold_utils.py"]:::modeling
        EuclidManifold["EuclideanManifold.py"]:::modeling
        PoincareManifold["PoincareManifold.py"]:::modeling
        ModelEuclid["model_Euclidean.py"]:::modeling
        ModelPoincare["model_Poincare.py"]:::modeling
    end

    %% Training & Evaluation Layer
    subgraph "Training & Evaluation Layer"
        Train["train_hyperbolic.py"]:::training
        Ablation["ablation_study_models.py"]:::training
        Utils["utils.py"]:::training
    end

    %% Output Layer
    subgraph "Output Layer"
        Checkpoints["Checkpoints & Logs"]:::output
    end

    %% Data Flow Connections
    RawCSVs -->|loads raw CSVs| SplitNotebook
    SplitNotebook -->|splits by city| BuildHyper
    SplitNotebook -->|splits by city| BuildMulti
    BuildHyper -->|builds hypergraph| PickledData
    BuildMulti -->|builds multigraph| PickledData

    PickledData -->|.pkl graph tensors| Prepare
    Config -->|provides hyperparameters| Train
    Config -->|provides paths| Prepare

    Prepare -->|constructs graphs| ManifoldUtils
    ManifoldUtils -->|embeds nodes| EuclidManifold
    ManifoldUtils -->|embeds nodes| PoincareManifold

    EuclidManifold -->|interface| ModelEuclid
    PoincareManifold -->|interface| ModelPoincare

    ModelEuclid -->|training loop| Train
    ModelPoincare -->|training loop| Train
    Utils -->|logging & metrics| Train

    Train -->|saves checkpoints & logs| Checkpoints
    Ablation -->|imports models & utils| ModelEuclid
    Ablation -->|imports models & utils| ModelPoincare
    Ablation -->|runs comparative eval| Utils

    %% Click Events
    click RawCSVs "https://github.com/liyongkang123/h3gnn/tree/main/data_preprocess/yongliu_gowalla_data"
    click SplitNotebook "https://github.com/liyongkang123/h3gnn/blob/main/data_preprocess/split_data_into_city.ipynb"
    click BuildHyper "https://github.com/liyongkang123/h3gnn/blob/main/data_preprocess/bulit_hypergraph.ipynb"
    click BuildMulti "https://github.com/liyongkang123/h3gnn/blob/main/data_preprocess/bulit_multigraph.ipynb"
    click PickledData "https://github.com/liyongkang123/h3gnn/tree/main/data/BER"
    click Config "https://github.com/liyongkang123/h3gnn/blob/main/config.py"
    click Prepare "https://github.com/liyongkang123/h3gnn/blob/main/prepare.py"
    click ManifoldUtils "https://github.com/liyongkang123/h3gnn/blob/main/manifold/manifold_utils.py"
    click EuclidManifold "https://github.com/liyongkang123/h3gnn/blob/main/manifold/EuclideanManifold.py"
    click PoincareManifold "https://github.com/liyongkang123/h3gnn/blob/main/manifold/PoincareManifold.py"
    click ModelEuclid "https://github.com/liyongkang123/h3gnn/blob/main/model_Euclidean.py"
    click ModelPoincare "https://github.com/liyongkang123/h3gnn/blob/main/model_Poincare.py"
    click Train "https://github.com/liyongkang123/h3gnn/blob/main/train_hyperbolic.py"
    click Ablation "https://github.com/liyongkang123/h3gnn/blob/main/ablation_study_models.py"
    click Utils "https://github.com/liyongkang123/h3gnn/blob/main/utils.py"

    %% Styles
    classDef data fill:#CFE2F3,stroke:#036;stroke-width:1px
    classDef preproc fill:#D9EAD3,stroke:#070;stroke-width:1px
    classDef config fill:#FFF2CC,stroke:#996600;stroke-width:1px
    classDef modeling fill:#FCE5CD,stroke:#B45F06;stroke-width:1px
    classDef training fill:#F4CCCC,stroke:#A61C1C;stroke-width:1px
    classDef output fill:#EAD1DC,stroke:#741B47;stroke-width:1px
    classDef external fill:#D9D9D9,stroke:#666666,stroke-width:1px
```
