RelatE: Relational Embeddings through Modulus-Phase Decomposition

Introduction

This is a PyTorch implementation of RelatE for learning embeddings in knowledge graphs (KGE). RelatE introduces enhancements that improve handling of complex relations (one-to-many, many-to-one, many-to-many) in knowledge graphs. The implementation is optimized for fast training on large-scale knowledge graphs and can achieve state-of-the-art performance on datasets like FB15K, WN18, and YAGO3-10.

The current RelatE scoring implementation follows the HAKE modulus-phase formulation closely; please cite HAKE alongside this repository when discussing the scoring function relationship.

Implemented Features

• ✔ Supports diverse relational patterns
• ✔ Enhanced Relation Expressiveness
• ✔ Improved Scoring Mechanism
• ✔ Efficient Training & Inference

Evaluation Metrics

We evaluate RelatE using the following standard KGE metrics:

• Mean Rank (MR): Measures the average rank of correct entities.
• Hits@10 (Filtered): Percentage of test triples where the correct entity is ranked in the top 10 after filtering out corrupted triples.

Loss Function:

• Uniform Negative Sampling
• Self-Adversarial Negative Sampling

Supported Datasets

Dataset	#R	#E	# (Train / Valid / Test)
FB15K	1,345	14,951	483,142 / 50,000 / 59,071
FB15K-237	237	14,541	272,115 / 17,535 / 20,466
WN18	18	40,943	141,442 / 5,000 / 5,000
WN18RR	11	40,943	86,835 / 3,034 / 3,134

Usage

Knowledge Graph Data Format:

The dataset consists of the following files:

• entities.dict – A dictionary mapping entities to unique IDs

• relations.dict – A dictionary mapping relations to unique IDs

• train.txt – The dataset used to train the KGE model

• valid.txt – The validation dataset

• test.txt – The dataset used to evaluate the KGE model

Testing

python run.py --do_test --data_path ./data/FB15K --init_checkpoint ./output/TransEEnhanced_FB15K --test_batch_size 16 --cuda

Env-Based Training Launcher

Use run.sh with a repo-local .env file so you can change GPU ids, hyperparameters, checkpoint cadence, and resume paths without rewriting the command line.

# edit .env or start from .env.example
bash run.sh

# or pass a different env file explicitly
bash run.sh path/to/experiment.env

Important .env fields:

• GPU_IDS=6 for one GPU or GPU_IDS=6,7 for multi-GPU training.
• INIT_CHECKPOINT=/path/to/checkpoint_dir to resume from a saved checkpoint.
• SAVE_CHECKPOINT_STEPS, VALID_STEPS, LOG_STEPS, and TEST_LOG_STEPS to control save/eval/log frequency.
• NEGATIVE_SAMPLE_SIZE, BATCH_SIZE, LEARNING_RATE, MODULUS_WEIGHT, PHASE_WEIGHT, and related fields for tuning.

If GPU_IDS contains multiple ids, driver.py will use DataParallel automatically.

Hyperparameters

Dataset	negative sample size n	hidden_dim d	margin g	adversarial temp a	batch size	mw init	pw init	learning rate	steps
FB15k	256	1000	12	1.0	1024	4.0	1.5	0.0001	100k
WN18	512	250	6	1.0	1024	3.5	1.5	0.0005	80k
FB15k-237	256	1000	12	1.0	1024	3.5	1.0	0.00005	120k
WN18RR (final verified run)	1024	500	6	0.5	512	0.5	0.5	0.00005	80k
YAGO3-10	512	2500	6	2.0	1024	5.5	2.5	0.0005	80k

Results of RelatE model

Dataset	MRR	HITS@1	HITS@3	HITS@10	Notes
WN18RR (final verified run)	0.496245	0.451181	0.512444	0.583121	2-GPU run on July 31, 2026 using -de -n 1024 -b 512 -d 500 -g 6.0 -a 0.5 -adv -lr 0.00005 -mw 0.5 -pw 0.5 --regularization 0.0

Additional WN18RR checkpoints from the same run:

• Validation MRR at step 10000: 0.482505
• Validation MRR at step 40000: 0.494148
• Learned final phase_weight: 0.02862533
• Learned final modulus_weight: 2.21389818

Knowledge Graph Embedding Repository Structure

This repository is designed for training and evaluating RelatE on several benchmark datasets.

Acknowledgement

We refer to the code of RotatE. Thanks for their contributions.