PoincareGCN-ConvE for Knowledge Graph Completion

This repository is a reusable reference implementation of the PoincareGCN-ConvE architecture proposed in Jingqi Fu's 2025 master's thesis, Research on the Construction and Application of Motor Fault Maintenance Knowledge Graph.

It demonstrates the model design and lets users train, evaluate, and rank missing links on their own knowledge graph triples. It does not contain the thesis's original motor fault knowledge graph, FB15k-237 files, trained weights, or experiment logs. It does not claim that the synthetic example or this independently engineered implementation reproduces the thesis metrics.

ASCII Poincare is used in package, repository, and command names for portability. It refers to the thesis model PoincaréGCN_ConvE.

Architecture

The implementation follows the thesis topology:

flowchart LR
    T["Knowledge graph triples"] --> E["Poincare entity and relation embeddings"]
    E --> G["Relation-aware Poincare CompGCN"]
    G --> D["Hyperbolic dropout and normalization"]
    D --> C["Hyperbolic Conv2D"]
    C --> A["Mobius ReLU"]
    A --> F["Hyperbolic linear layer"]
    F --> Q["Query embedding"]
    Q --> S["Poincare distance to all entities"]
    S --> R["Filtered tail/head ranking"]

Loading

Key design choices:

• entity and forward/inverse relation embeddings are mapped into a Poincare ball;
• relation-aware GCN messages compose a neighboring entity with its relation and aggregate graph context;
• hyperbolic linear, dropout, normalization, activation, and convolution layers operate by mapping to the origin tangent space and back;
• a ConvE-style decoder reshapes the concatenated head/relation representation, applies two-dimensional convolution, and maps the result to a query embedding;
• candidate entities are ranked by negative Poincare distance;
• both tail prediction (h, r, ?) and head prediction (?, r, t) are supported through explicit inverse relations.

See docs/architecture.md for the exact tensor flow and documented implementation decisions.

Scope and reproducibility statement

This repository provides:

• a self-contained PyTorch implementation of Poincare geometry;
• relation-aware Poincare graph convolution;
• hyperbolic ConvE-style decoding;
• strict TSV parsing and train-schema validation;
• forward and inverse query generation;
• multi-target one-vs-all training with optional label smoothing;
• filtered MRR, mean rank, and Hits@K evaluation;
• best-checkpoint restoration and early stopping on development MRR;
• validation, splitting, training, evaluation, and prediction commands;
• synthetic examples, tests, packaging, CI, citation, and license metadata.

This repository does not provide:

• the thesis's proprietary motor fault maintenance graph or raw source data;
• FB15k-237 or any other third-party benchmark dataset;
• the exact historical source code, checkpoint, environment, data ordering, or all undocumented preprocessing and initialization choices;
• GPB extraction, BAC entity recognition, Neo4j import, or the ChatGLM3 question-answering system;
• a guarantee of reproducing thesis curves or numerical results.

The thesis reports, after 500 epochs on FB15k-237, approximately 0.35 Hits@1, 0.47 Hits@3, 0.54 Hits@5, and 0.45 MRR for PoincareGCN-ConvE. It describes relative improvements over CompGCN-ConvE of roughly 30%, 23%, 20%, and 25%. These are thesis-reported results, not results generated by this public repository.

Installation

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

PyTorch installation can be platform-specific. Install the matching CUDA wheel first when needed. geoopt is used for the thesis-reported Riemannian Adam optimizer choice.

Data format

Each UTF-8 TSV line is one binary knowledge graph triple:

HEAD<TAB>RELATION<TAB>TAIL

Example:

overheat	caused_by	bearing_wear
bearing_wear	resolved_by	replace_bearing

Identifiers are opaque strings and may represent any domain. Development and test entities and relations must occur in training; this is the transductive link-prediction setting used by the implementation. Full rules are in docs/data_format.md.

Validate and split

poincare-validate path/to/all.tsv

poincare-split path/to/all.tsv path/to/splits \
  --train-ratio 0.8 --dev-ratio 0.1 --test-ratio 0.1 --seed 42

The convenience splitter moves triples back to training when necessary to keep every dev/test entity and relation in the training schema. For benchmark-quality work, use an official split or construct leakage-resistant splits before training.

Train

poincare-train \
  --config configs/poincare_gcn_conve.yaml \
  --train path/to/train.tsv \
  --dev path/to/dev.tsv \
  --test path/to/test.tsv \
  --output artifacts/my-model

The artifact contains model weights, entity/relation vocabularies, training graph triples, resolved configuration, training history, and metrics. Test data is evaluated only after the best development-MRR checkpoint is restored.

Three configurations are intentionally separate:

• configs/poincare_gcn_conve.yaml: practical general starting point;
• configs/paper_reported.yaml: thesis-reported hyperparameters, without a reproducibility guarantee;
• configs/offline_smoke.yaml: tiny process check used by tests, never a benchmark.

Evaluate

poincare-evaluate \
  --checkpoint artifacts/my-model \
  --data path/to/test.tsv \
  --filter-data path/to/dev.tsv

Training triples and evaluation triples are always included in filtered ranking. Supply other known-true splits with repeated --filter-data so alternative correct answers are not counted against the model.

Predict missing links

poincare-predict \
  --checkpoint artifacts/my-model \
  --head overheat \
  --relation caused_by \
  --top-k 5

The command ranks candidate tails already present in the training entity vocabulary. It does not automatically write predictions back to a database; review predicted links before any knowledge graph mutation.

Practical recommendations

• Preserve one canonical identifier per entity and relation.
• Remove exact duplicates and audit reciprocal/inverse leakage before splitting.
• Include all known true triples in the filter set during evaluation.
• Report head and tail prediction together with filtered MRR and Hits@K.
• Tune curvature, dimensions, dropout, label smoothing, and learning rate on development data; do not tune against test metrics.
• Treat Poincare operations as geometry-sensitive: use float32 or float64, monitor norms, and keep embeddings inside the ball.
• Treat the synthetic examples as a workflow demonstration, not performance evidence.

Development

python -m pip install -e ".[dev]"
ruff check .
pytest -q

Continuous integration runs these checks on Python 3.10 and 3.12.

License and citation

The code is released under the MIT License. Citation metadata is available in CITATION.cff. If this implementation contributes to academic work, cite the associated thesis and clearly distinguish results obtained with your data and code version from the thesis-reported results.