KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

HyDRA

★ 160 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1>

✨ Towards Temporal Knowledge Graph Alignment in the Wild ✨

</h1>

</div>

[![Version 1.0.0](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/eduzrh/HyDRA)
[![Language: Python 3](https://img.shields.io/badge/Language-Python3-blue.svg?style=flat-square)](https://www.python.org/)
[![Made with PyTorch](https://img.shields.io/badge/Made%20with-pytorch-orange.svg?style=flat-square)](https://www.pytorch.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://raw.githubusercontent.com/eduzrh/HyDRA/main/LICENSE)
[![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-brightgreen.svg?style=flat-square)](https://github.com/eduzrh/HyDRA/issues)

[English](README.md) | [简体中文](./README_zh_CN.md)

</div>

<p align="center">
  <a href="#-introduction"><b>📰 Introduction</b></a> |
  <a href="#architecture"><b>🏗️ Architecture</b></a> |
  <a href="#installation"><b>⚙️ Installation</b></a> |
  <a href="#-quick-start"><b>🚀 Quick Start</b></a> <br>
  <a href="#-datasets"><b>📦 Datasets</b></a> |
  <a href="#-usage"><b>📖 Usage</b></a> |
  <a href="#-reproducibility"><b>🔬 Reproducibility</b></a> |
  <a href="#-license"><b>📜 License</b></a> |
  <a href="#-contact"><b>📬 Contact</b></a>
  <a href="#-citation"><b>📑 Citation</b></a>
</p>

---

## 📰 Latest News

| 🆕 Updates          | 📅 Date | 📝 Description                            |
| ------------------- | ------- | ----------------------------------------- |
| 🎉 **Code Release** | -       | HyDRA codebase and datasets now available |

> **Before running:** After cloning, unzip the bundled archives in the repo root and under `data/` (at minimum `encoding_and_integration.zip`; optionally `Preprocess.zip` for large-scale experiments).

---

## 📰 Introduction

**Temporal Knowledge Graph Alignment in the Wild (TKGA-Wild)** addresses a critical challenge in temporal knowledge graph integration. To the best of our knowledge, this is the **first work** to formally formulate and solve this problem, which we term **TKGA-Wild**. This task presents unique challenges due to **Multi-Scale Temporal Elements** (i.e., multi-granular temporal coexistence and temporal span disparity) and **Asymmetric Temporal Structures** (i.e., heterogeneous temporal structures and temporal structural incompleteness) that are common in real-world scenarios.

We have officially introduced complete and high-quality TKGA-Wild benchmarks and proposed **HyDRA**, a new paradigm based on **multi-scale hypergraph retrieval-augmented generation** to systematically address the unique challenges of TKGA-Wild. HyDRA effectively captures complex structural dependencies, models multi-granular temporal features, mitigates temporal disparities, and introduces a new **scale-weave synergy mechanism** to coordinate information across different temporal scales.

## 🔥 Key Features

| Feature                                 | Icon | Description                                                                                      |
| --------------------------------------- | ---- | ------------------------------------------------------------------------------------------------ |
| **Multi-Granularity Temporal Encoding** | 🔄   | Captures temporal information at different scales (year, month, day)                             |
| **Scale-Adaptive Entity Projection**    | 📐   | Adaptive entity projection across different graph scales and dimensions                          |
| **Multi-Scale Hypergraph Retrieval**    | 🔍   | Efficient neural retrieval for hypergraph-based search                                           |
| **Scale-Weave Synergy**                 | 🔗   | Coordinates information across different temporal scales                                         |
| **State-of-the-Art Performance**        | 📈   | Consistently outperforming 28 competitive baselines, achieving up to 43.3% improvement in Hits@1 |

---

## 🏗️ Architecture

HyDRA adopts a **multi-scale hypergraph retrieval-augmented generation** paradigm, comprising several key stages:

Stage 1: Encoding and Integration 🔄

Stage 2: Scale-Adaptive Entity Projection 📐

Stage 3: Multi-Scale Hypergraph Retrieval 🔍

Stage 4: Multi-Scale Fusion 🔗

> 📖 For detailed architecture descriptions and theoretical foundations, refer to the accompanying paper.

---

## ⚙️ Installation

### 📋 Prerequisites

First, install dependencies:

```bash

pip install -r requirements.txt

```

### 📦 Main Dependencies

| Package         | Version   | Purpose                               |
| --------------- | --------- | ------------------------------------- |
| 🐍 **Python**   | >= 3.7    | Core language (tested on 3.8.10)      |
| 🔥 **PyTorch**  | >= 1.10.0 | Deep learning framework               |
| 🔍 **Faiss**    | >= 1.7.0  | Efficient similarity search (CPU/GPU) |
| 📊 **NumPy**    | >= 1.21.0 | Numerical computing                   |
| 🐼 **Pandas**   | >= 1.3.0  | Data manipulation                     |
| ⏳ **Tqdm**      | >= 4.62.0 | Progress bars                         |
| 🌐 **NetworkX** | >= 2.6.0  | Graph analysis                        |

> 💡 **Note:** For GPU-accelerated FAISS, use `faiss-gpu` instead of `faiss-cpu`.

---

## 📦 Datasets

For our newly proposed **TKGA-Wild** scenario, we introduce two novel benchmark datasets: **BETA** and **WildBETA**.

| Dataset      | Description                              | Fact Size |
| ------------ | ---------------------------------------- | --------- |
| **BETA**     | Benchmark dataset for TKGA-Wild          | 362K+     |
| **WildBETA** | Extended benchmark dataset for TKGA-Wild | 563K+     |

### 🔗 Download Links

[![Baidu Netdisk](https://img.shields.io/badge/Baidu_Netdisk-Download-blue?style=for-the-badge)](https://pan.baidu.com/s/1TKZvjsDgqUrOAGKe6MRf9A?pwd=pnax)
[![Google Drive](https://img.shields.io/badge/Google_Drive-Download-green?style=for-the-badge)](https://drive.google.com/drive/folders/1P-YtGgoEh_y2RwKTS-YeM0X1sdWlWDEV?usp=sharing)

</div>

> 🔐 **Baidu Netdisk**: Extraction Code: `pnax` | Password: `tkgawild`

**Dataset Format:**

Take the dataset `icews_wiki` as an example, the folder `data/icews_wiki/` should contain:

- `ent_ids_1`: Entity IDs in source KG
- `ent_ids_2`: Entity IDs in target KG
- `triples_1`: Relation triples encoded by IDs in source KG
- `triples_2`: Relation triples encoded by IDs in target KG
- `rel_ids_1`: Relation IDs in the source KG
- `rel_ids_2`: Relation IDs in the target KG
- `time_id`: Time IDs in the source KG and the target KG
- `ref_ent_ids`: All aligned entity pairs, list of pairs like `(e_s \t e_t)`

**Note:** The representative datasets used in experiments are derived from [Dual-AMN](https://github.com/MaoXinn/Dual-AMN), [JAPE](https://github.com/nju-websoft/JAPE), [GCN-Align](https://github.com/1049451037/GCN-Align), [BETA](https://github.com/DexterZeng/BETA), [DAEA](https://github.com/yangxiaoxiaoly/DAEA), [AGROLD, DOREMUS](https://github.com/EnsiyehRaoufi/Create_Input_Data_to_EA_Models), [TimeD1M/EN-FR, TimeD1M/EN-DE, Time-FB2M](https://huggingface.co/datasets/knowledgeAnonymous/LargeTKGA), [DBP1M/EN-FR, DBP1M/EN-DE](https://drive.google.com/file/d/15jeGD-6pVGlqI5jCn7KJfGIER6AeoQ-L/view?usp=sharing), [FBDBP2M](https://1drv.ms/u/s!Ar-uYoG1mfiLkx97L7j4MrVUMazO?e=8SSjgt) and related works.

### Large-Scale Preprocessing

For large-scale preprocessing details, see [Preprocess/README.md](Preprocess/README.md).

---

## 🚀 Quick Start

### Step 1: Clone the Repository 📥

```bash

git clone https://github.com/eduzrh/HyDRA.git

cd HyDRA

```

### Step 2: Prepare Datasets 📦

Download and extract datasets to `./data/`

### Step 3: Run the Main Experiment ▶️

```bash

python HyDRA_main.py --data_dir data/WildBETA

```

### Step 4: View Results 📊

| Metric      | Description                                   |
| ----------- | --------------------------------------------- |
| **Hits@1**  | Proportion of correct alignments ranked first |
| **Hits@10** | Proportion in top-10 candidates               |
| **MRR**     | Mean Reciprocal Rank                          |

---

## 📖 Usage

### Basic Usage

**Run complete pipeline:**

```bash

python HyDRA_main.py --data_dir data/WildBETA

```

### Advanced Options

**Configure training parameters:**

```bash

python HyDRA_main.py --data_dir data/WildBETA \

--cuda 0 \

--epochs 1500 \

--max_iterations 5 \

--min_kg1_entities 100

```

**Parameter Descriptions:**

| Parameter            | Type  | Default      | Description                                                                      |
| -------------------- | ----- | ------------ | -------------------------------------------------------------------------------- |
| `--data_dir`         | str   | **Required** | Path to dataset directory                                                        |
| `--cuda`             | int   | 0            | CUDA device ID for training                                                      |
| `--epochs`           | int   | 500          | Number of training epochs for encoding stage                                     |
| `--max_iterations`   | int   | 3            | Maximum pipeline iterations                                                      |
| `--min_kg1_entities` | int   | 50           | Minimum entities threshold for stopping                                          |
| `--add_noise`        | flag  | off          | Sec. 5.6: mask name-embedding dims in Stage 1 (Simple-HHEA)                      |
| `--noise_ratio`      | float | 0.0          | Fraction of 64-d name-embedding dims to zero when `--add_noise` is set (0.0–1.0) |

### Multi-Granularity Time Modeling

HyDRA supports multi-granularity temporal modeling (year and month levels) to handle Multi-Granular Temporal Coexistence. Enable it with `--multi_granularity_time` on `HyDRA_main.py` (recommended for BETA and WildBETA).

### Robustness under Embedding Noise (Sec. 5.6)

Paper Sec. 5.6 injects degradation into entity name embeddings in Stage 1. The full pipeline forwards `--add_noise` and `--noise_ratio` to Simple-HHEA (randomly zeroing a fraction of the 64-d name-embedding dimensions):

```bash

python HyDRA_main.py --data_dir WildBETA --multi_granularity_time \

--add_noise --noise_ratio 0.8

```

Use `--noise_ratio` from `0.0` to `1.0` (e.g. `0.8` for 80%). Default main results omit noise (do not pass `--add_noise`).

---

## 🔬 Reproducibility

We are committed to ensuring full reproducibility of our results. The following resources are provided:

### 📋 Experimental Configuration

- **Hyperparameters**: All hyperparameter settings are documented in the code and can be configured via command-line arguments
- **Random Seeds**: Seed configurations are embedded in the training scripts for reproducibility
- **Environment**: Tested on Python 3.8.10 with dependencies as specified in `requirements.txt`

### 📊 Reproducing Main Results

To reproduce the main experimental results reported in the paper:

1. **Download datasets** following the format described in the Datasets section
2. **Run the complete pipeline** with default settings:

```bash

python HyDRA_main.py --data_dir data/WildBETA

```

1. **Evaluate results** using the output files in `data/icews_wiki/message_pool/`

### 🏗️ Code Organization

The codebase is organized into modular components for clarity:

- `encoding_and_integration/`: Multi-granularity temporal entity encoding and integration
- `scale_adaptive_entity_projection/`: Relation alignment and entity projection
- `multi_scale_hypergraph_retrieval/`: Neural retrieval and hypergraph decomposition
- `multi_scale_fusion/`: Multi-scale fusion and alignment refinement
- `HyDRA_main.py`: Main pipeline orchestrator

### 📝 Documentation

- Comprehensive inline code comments explaining key design decisions
- Clear module structure with standardized naming conventions
- This README with step-by-step usage instructions

---

## 📊 Evaluation Metrics

We employ standard knowledge graph alignment metrics for transparency and comparability:

- **Hits@1**: Proportion of correct alignments ranked first
- **Hits@10**: Proportion of correct alignments in top-10 candidates  
- **MRR (Mean Reciprocal Rank)**: Average reciprocal rank of correct alignments

## 📜 License

[MIT License](LICENSE) - Copyright notices preserved.

## 📬 Contact

- **Email**: [runhaozhao@nudt.edu.cn](mailto:runhaozhao@nudt.edu.cn)
- **GitHub Issues**: For technical concerns, create an Issue in the [GitHub repository](https://github.com/eduzrh/HyDRA/issues). Labels: `bug`, `enhancement`, `question`.

Responses targeted within 2-3 business days.

## 📑 Citation

If you find this work helpful for your research or applications, we would appreciate it if you could cite the following paper:

```bibtex
@article{DBLP:journals/corr/abs-2507-14475,
  author       = {Runhao Zhao and
                  Weixin Zeng and
                  Wentao Zhang and
                  Xiang Zhao and
                  Jiuyang Tang and
                  Lei Chen},
  title        = {Towards Temporal Knowledge Graph Alignment in the Wild},
  journal      = {CoRR},
  volume       = {abs/2507.14475},
  year         = {2025},
  url          = {https://doi.org/10.48550/arXiv.2507.14475},
  doi          = {10.48550/ARXIV.2507.14475},
  eprinttype   = {arXiv},
  eprint       = {2507.14475}
}
```

---

## 🔗 References

- [EasyEA: Large Language Model is All You Need in Entity Alignment Between Knowledge Graphs](https://aclanthology.org/2025.findings-acl.1080/).
Jingwei Cheng, Chenglong Lu, Linyan Yang, Guoqing Chen, and Fu Zhang.
Findings of the Association for Computational Linguistics (ACL Findings), 2025.
- [On entity alignment at scale](https://link.springer.com/article/10.1007/s00778-021-00703-3).
Weixin Zeng, Xiang Zhao, Xinyi Li, Jiuyang Tang, and Wei Wang.
The VLDB Journal, 2022.
- [High-quality Task Division for Large-scale Entity Alignment](https://dl.acm.org/doi/10.1145/3511808.3557352).
Binfeng Liu, Wen Hua, Guido Zuccon, Genghao Zhao, and Xike Zhang.
Proceedings of the ACM International Conference on Information and Knowledge Management (CIKM), 2022.
- [Enhancing Large-scale Entity Alignment with Critical Structure and High-quality Context](https://ieeexplore.ieee.org/document/11113003).
Qian Zhou, Chen Wei, Zhang Li, Zhao Pengpeng, Xu Jiajie, and Zhao Lei.
IEEE International Conference on Data Engineering (ICDE), 2025.
- [Unsupervised Entity Alignment for Temporal Knowledge Graphs](https://doi.org/10.1145/3543507.3583381).
Xiaoze Liu, Junyang Wu, Tianyi Li, Lu Chen, and Yunjun Gao.
Proceedings of the ACM Web Conference (WWW), 2023.
- [BERT-INT: A BERT-based Interaction Model for Knowledge Graph Alignment](https://doi.org/10.1145/3543507.3583381).
Xiaobin Tang, Jing Zhang, Bo Chen, Yang Yang, Hong Chen, and Cuiping Li.
Journal of Artificial Intelligence Research, 2020.
- [Benchmarking Challenges for Temporal Knowledge Graph Alignment](https://api.semanticscholar.org/CorpusID:273501043).
Weixin Zeng, Jie Zhou, and Xiang Zhao.
Proceedings of the ACM International Conference on Information and Knowledge Management (CIKM), 2024.
- [Cross-lingual Knowledge Graph Alignment via Graph Convolutional Networks](https://doi.org/10.18653/v1/d18-1032).
Zhichun Wang, Qingsong Lv, Xiaohan Lan, and Yu Zhang.
Proceedings of the Conference on Empirical Methods in Natural Language Processing (EMNLP), 2018.
- [Boosting the Speed of Entity Alignment 10×: Dual Attention Matching Network with Normalized Hard Sample Mining](https://doi.org/10.1145/3442381.3449897).
Xin Mao, Wenting Wang, Yuanbin Wu, and Man Lan.
Proceedings of the Web Conference (WWW), 2021.
- [Wikidata: A Free Collaborative Knowledgebase](https://doi.org/10.1145/2629489).
Denny Vrandecic and Markus Krötzsch.
Communications of the ACM, 2014.
- [Toward Practical Entity Alignment Method Design: Insights from New Highly Heterogeneous Knowledge Graph Datasets](https://doi.org/10.1145/3589334.3645720).
Xuhui Jiang, Chengjin Xu, Yinghan Shen, Yuanzhuo Wang, Fenglong Su, Zhichao Shi, Fei Sun, Zixuan Li, Jian Guo, and Huawei Shen.
Proceedings of the ACM Web Conference (WWW), 2024.
- [Unlocking the Power of Large Language Models for Entity Alignment](https://aclanthology.org/2024.acl-long.408).
Xuhui Jiang, Yinghan Shen, Zhichao Shi, Chengjin Xu, Wei Li, Zixuan Li, Jian Guo, Huawei Shen, and Yuanzhuo Wang.
Proceedings of the Annual Meeting of the Association for Computational Linguistics (ACL), 2024.
- [Bootstrapping Entity Alignment with Knowledge Graph Embedding](https://doi.org/10.24963/ijcai.2018/611).
Zequn Sun, Wei Hu, Qingheng Zhang, and Yuzhong Qu.
Proceedings of the International Joint Conference on Artificial Intelligence (IJCAI), 2018.
- [NetworkX: Network Analysis in Python](https://github.com/networkx/networkx).
NetworkX Developers.
GitHub Repository.
- [Faiss: A Library for Efficient Similarity Search and Clustering of Dense Vectors](https://github.com/facebookresearch/faiss).
Facebook Research.
GitHub Repository.
- [DAEA: Enhancing Entity Alignment in Real-World Knowledge Graphs Through Multi-Source Domain Adaptation](https://aclanthology.org/2025.coling-main.393/)
Linyan Yang, Shiqiao Zhou, Jingwei Cheng, Fu Zhang, Jizheng Wan, Shuo Wang, Mark Lee.
COLING 2025
- [TGB 2.0: A Benchmark for Learning on Temporal Knowledge Graphs and Heterogeneous Graphs](https://arxiv.org/abs/2406.09639)
Julia Gastinger, Shenyang Huang, Mikhail Galkin, Erfan Loghmani, Ali Parviz, Farimah Poursafaei, Jacob Danovitch, Emanuele Rossi, Ioannis Koutis, Heiner Stuckenschmidt, Reihaneh Rabbany, Guillaume Rabusseau.
NeurIPS 2024 Track on Datasets and Benchmarks

## 🙏 Acknowledgement

The following open source projects were partially referenced in this work. We sincerely appreciate their contributions:

[Dual-AMN](https://github.com/MaoXinn/Dual-AMN), [JAPE](https://github.com/nju-websoft/JAPE), [GCN-Align](https://github.com/1049451037/GCN-Align), [Simple-HHEA](https://github.com/jxh4945777/Simple-HHEA), [BETA](https://github.com/DexterZeng/BETA), [Dual-Match](https://github.com/ZJU-DAILY/DualMatch/), [Faiss](https://github.com/facebookresearch/faiss), [NetworkX](https://github.com/networkx/networkx), [AdaCoAgentEA](https://github.com/eduzrh/AdaCoAgentEA), [DAEA](https://github.com/yangxiaoxiaoly/DAEA), [AGROLD, DOREMUS](https://github.com/EnsiyehRaoufi/Create_Input_Data_to_EA_Models), [LargeTKGA Datasets](https://huggingface.co/datasets/knowledgeAnonymous/LargeTKGA), [LargeKGA Datasets](https://github.com/DexterZeng/LIME),[ELsEA](https://github.com/wx-qzhou/ELsEA)

---

This repository corresponds to the paper ***Towards Temporal Knowledge Graph Alignment in the Wild*** (under review at *IEEE TPAMI*), and is an extension of our previous work [BETA](https://github.com/DexterZeng/BETA).

HyDRA

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README