# zjukg/ankge architecture

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

- Interactive diagram: https://gitdiagram.com/zjukg/ankge
- Repository: https://github.com/zjukg/ankge

## Overview

##### Project type and purpose
- This is a research‐oriented machine‐learning pipeline for Knowledge Graph Embedding (KGE), enhanced by an analogical inference framework (AnKGE).
- Its goal is to load benchmark KG datasets (FB15K‐237, WN18RR), train base embedding models (TransE, RotatE, HAKE, PairRE), augment them with analogical inference at entity, relation, and triple levels, and evaluate on link prediction.

##### File structure
- Top level
- dataset/ : raw KG data (entities.dict, relations.dict, train/valid/test splits)
- scripts/ : shell scripts to run experiments (base model and AnKGE on FB and WN)
- src/ankge/ : core code organized into subpackages
- main.py : global entrypoint
- src/ankge subpackages
- data/ : data preprocessing, sampling, PyTorch‐Lightning DataModule
- model/KGEModel/ : implementations of base KG models
- loss/ : definitions of loss functions for base and analogical training
- lit_model/ : PyTorch‐Lightning “LightningModule” wrappers for training logic
- eval_task/ : evaluation code (link_prediction)
- utils/ : argument parsing, helper tools
- Config and orchestration
- requirements.txt for dependencies
- .sh scripts set hyperparameters, BASE_MODEL_PATH, and invoke main.py

##### README for additional insights
- Describes the 3‐stage AnKGE process: retrieve analogical objects → train analogy functions → interpolate analogy score with base model score
- Notes use of PyTorch Lightning, wandb for logging, GPU requirements
- Illustrates the model architecture (AnKGE_structure.png)

a. Main components
1. Dataset Storage
- FB15K‐237 folder, WN18RR folder
2. Data Preprocessing & Loader
- DataPreprocess.py, Sampler.py, RuleDataLoader.py → KGDataModule (PyTorch Lightning)
3. Base KGE Models
- TransE, RotatE, HAKE, PairRE implementations under model/KGEModel/
4. Analogical Inference Module (AnKGE)
- GetNearNeighbor, GetLevelScore, Grounding → analogy functions per level
5. Loss Functions
- AnKnn_Loss, Adv_Loss
6. Training Orchestrator
- AnKnnLitModel, KGELitModel, KGERevLitModel (LightningModule)
- Trainer abstraction provided by PyTorch Lightning and main.py
7. Evaluation
- link_prediction code under eval_task
8. Experiment Controller
- Shell scripts in scripts/ to launch base and AnKGE experiments
9. Logging & Output
- wandb API, output/link_prediction/, logging/

b. Relationships & interactions
- Base model component feeds embeddings into Analogy module
- Analogy module outputs analogical scores merged with base scores
- Loss functions take combined scores + ground truth for backprop
- Evaluation pulls trained model checkpoints to compute metrics
- Shell scripts orchestrate sequential runs: base model first → AnKGE training

c. Architectural patterns & principles
- Modular pipeline: clear separation between data, model, analogy, loss, training, evaluation
- Extensibility: supports plugging in new base models or analogy functions
- Use of PyTorch Lightning enforces uniform Trainer/DataModule/LightningModule pattern

d. Key technologies & frameworks
- Python 3, PyTorch, PyTorch Lightning
- numpy, tqdm, wandb for logging/monitoring
- shell scripts for reproducible experiments

##### Detailed pointers
- Start at “scripts” level: show how a shell script invokes main.py with parameters pointing to dataset and BASE_MODEL_PATH
- Drill down: main.py parses arguments via setup_parser → instantiates KGDataModule → selects KGEModel class → wraps it in the chosen LightningModule → configures Trainer (GPU, wandb) → Trainer.fit → saves checkpoints
- On AnKGE runs, reflect an extra block: “Analogy Retrieval & Scoring” that taps into embedding space and outputs analogical embeddings/scores, then merges them
- Finally, after training, Trainer.test triggers link_prediction evaluation module, writing to output/link_prediction/*

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Experiment Controller"
        ScriptsFB["FB Shell Scripts"]:::scripts
        ScriptsWN["WN Shell Scripts"]:::scripts
        click ScriptsFB "https://github.com/zjukg/ankge/blob/main/scripts/FreeBase/*.sh"
        click ScriptsWN "https://github.com/zjukg/ankge/blob/main/scripts/WordNet/*.sh"
    end

    ScriptsFB --> main
    ScriptsWN --> main

    main["main.py"]:::orchestrator
    click main "https://github.com/zjukg/ankge/blob/main/main.py"

    main --> Parser["setup_parser.py"]:::utils
    click Parser "https://github.com/zjukg/ankge/blob/main/src/ankge/utils/setup_parser.py"

    subgraph "Data Layer"
        DatasetFB["FB15K-237"]:::data
        DatasetWN["WN18RR"]:::data
        click DatasetFB "https://github.com/zjukg/ankge/tree/main/dataset/FB15K237/"
        click DatasetWN "https://github.com/zjukg/ankge/tree/main/dataset/WN18RR/"
        DP["DataPreprocess.py"]:::data
        click DP "https://github.com/zjukg/ankge/blob/main/src/ankge/data/DataPreprocess.py"
        Sampler["Sampler.py"]:::data
        click Sampler "https://github.com/zjukg/ankge/blob/main/src/ankge/data/Sampler.py"
        RL["RuleDataLoader.py"]:::data
        click RL "https://github.com/zjukg/ankge/blob/main/src/ankge/data/RuleDataLoader.py"
        BaseDM["base_data_module.py"]:::data
        click BaseDM "https://github.com/zjukg/ankge/blob/main/src/ankge/data/base_data_module.py"
        KGDM["KGDataModule.py"]:::data
        click KGDM "https://github.com/zjukg/ankge/blob/main/src/ankge/data/KGDataModule.py"
    end

    Parser --> DatasetFB
    Parser --> DatasetWN
    DatasetFB --> DP --> Sampler --> RL --> BaseDM --> KGDM
    DatasetWN --> DP

    subgraph "Model Layer"
        subgraph "Base KGE Models"
            TransE["TransE.py"]:::model
            click TransE "https://github.com/zjukg/ankge/blob/main/src/ankge/model/KGEModel/TransE.py"
            RotatE["RotatE.py"]:::model
            click RotatE "https://github.com/zjukg/ankge/blob/main/src/ankge/model/KGEModel/RotatE.py"
            HAKE["HAKE.py"]:::model
            click HAKE "https://github.com/zjukg/ankge/blob/main/src/ankge/model/KGEModel/HAKE.py"
            PairRE["PairRE.py"]:::model
            click PairRE "https://github.com/zjukg/ankge/blob/main/src/ankge/model/KGEModel/PairRE.py"
            modelpy["model.py"]:::model
            click modelpy "https://github.com/zjukg/ankge/blob/main/src/ankge/model/KGEModel/model.py"
        end
        subgraph "Analogical Inference Module"
            GNN["GetNearNeighbor.py"]:::model
            click GNN "https://github.com/zjukg/ankge/blob/main/src/ankge/data/GetNearNeighbor.py"
            GLS["GetLevelScore.py"]:::model
            click GLS "https://github.com/zjukg/ankge/blob/main/src/ankge/data/GetLevelScore.py"
            GR["Grounding.py"]:::model
            click GR "https://github.com/zjukg/ankge/blob/main/src/ankge/data/Grounding.py"
            AnKnnModel["AnKnn.py"]:::model
            click AnKnnModel "https://github.com/zjukg/ankge/blob/main/src/ankge/model/KGEModel/AnKnn.py"
        end
    end

    KGDM --> TransE
    KGDM --> RotatE
    KGDM --> HAKE
    KGDM --> PairRE
    KGDM --> modelpy
    KGDM --> GNN
    KGDM --> GLS
    KGDM --> GR
    KGDM --> AnKnnModel
    TransE -->|embeddings| GNN
    modelpy -->|base scores| GLS

    subgraph "Loss Layer"
        AnKnnLoss["AnKnn_Loss.py"]:::loss
        click AnKnnLoss "https://github.com/zjukg/ankge/blob/main/src/ankge/loss/AnKnn_Loss.py"
        AdvLoss["Adv_Loss.py"]:::loss
        click AdvLoss "https://github.com/zjukg/ankge/blob/main/src/ankge/loss/Adv_Loss.py"
    end

    GNN --> AnKnnLoss
    GLS --> AdvLoss
    GR --> AnKnnLoss

    subgraph "Training Layer"
        BaseLit["BaseLitModel.py"]:::train
        click BaseLit "https://github.com/zjukg/ankge/blob/main/src/ankge/lit_model/BaseLitModel.py"
        KGELit["KGELitModel.py"]:::train
        click KGELit "https://github.com/zjukg/ankge/blob/main/src/ankge/lit_model/KGELitModel.py"
        KGERevLit["KGERevLitModel.py"]:::train
        click KGERevLit "https://github.com/zjukg/ankge/blob/main/src/ankge/lit_model/KGERevLitModel.py"
        AnKnnLit["AnKnnLitModel.py"]:::train
        click AnKnnLit "https://github.com/zjukg/ankge/blob/main/src/ankge/lit_model/AnKnnLitModel.py"
        Trainer["PyTorch Lightning Trainer"]:::train
    end

    KGDM --> BaseLit
    KGDM --> KGELit
    KGDM --> KGERevLit
    KGDM --> AnKnnLit
    TransE --> KGELit
    RotatE --> KGELit
    HAKE --> KGELit
    PairRE --> KGELit
    AnKnnModel --> AnKnnLit
    AnKnnLoss --> AnKnnLit
    AdvLoss --> AnKnnLit
    BaseLit --> Trainer
    KGELit --> Trainer
    KGERevLit --> Trainer
    AnKnnLit --> Trainer

    subgraph "Evaluation Layer"
        Eval["link_prediction.py"]:::eval
        click Eval "https://github.com/zjukg/ankge/blob/main/src/ankge/eval_task/link_prediction.py"
    end

    Trainer --> Eval

    classDef data fill:#bbf,stroke:#55f;
    classDef model fill:#bfb,stroke:#5b5;
    classDef loss fill:#fea,stroke:#fa0;
    classDef train fill:#ffb,stroke:#fb5;
    classDef eval fill:#f99,stroke:#f55;
    classDef scripts fill:#cdf,stroke:#5af;
    classDef utils fill:#dfd,stroke:#5a5;
    classDef orchestrator fill:#ffeb99,stroke:#dbb;
```
