Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Hyperbolic N-Space Embeddings for TensorFlow


Hyperbolic n-space, is a maximally symmetric, n-dimensional Riemannian manifold with constant negative sectional curvature. It turns out that hyperbolic space is very well suited for representing hierarchical data because it 'curves' space, allowing parent and sibling distances to stay constant over many branches without needing to increase dimensionality, as is the case in Euclidean space. A relatively intuitive model for thinking of embeddings in hyperbolic space is the poincare ball, where you can think of distances that increase exponentially as you move out from the center of the disk/ball.

This is an implementation of some basic functions for supporting hyperbolic geometries in the Poincare model (Lorentz to come) as well as functions to calculate riemann gradients over hyperbolic riemann manifolds.


Getting Started

Install the dependencies in your working environment, listed in requirements.txt and environment.yml

# if using venv
virtualenv .
source venv/bin/activate
pip install -r requirements.txt

# or, with conda
conda env create -f environment.yml
source activate poincare

# or, just pip install with your working python env

The first thing you'll need to do is compile the cython modules that load the datasets.

python build_ext --inplace

Then, to run the demos, generate a transitive closure of hyper and hypo -nym relations from wordnet.

cd wordnet
# this will generate the transitive closure over wordnet nouns, as well as a mammal subtree closure

Then, to train an embedding:

# either use the default parameters

# or run with your own parameters
python3 \
       -dim 10 \
       -lr 0.5 \
       -epochs 100 \
       -negs 50 \
       -burnin 10 \
       -dset wordnet/mammal_closure.csv \
       -checkpoint checkpoints/ \
       -batchsize 30 \
       -eval_each 1

A similar script exists for the noun closure, but be warned it is very large.


The entry-point here is usually which is an executable that will initialize a new TF model and vector space embedding and train it.

There's only the Poincare manifold at the moment, but the Lorentz should come next.

There's an optimizer that's not used in the demos, but runs the optimization over the particular manifold. will do basic visualizations over a poincare disk or, experimentally using umap dimensionality squashing.

Training uses a sparse softmax cross entropy for loss, which doesn't necessarily have to be the case, but is a good default measure here, where we want to push the negative samples for each hypernym example away from the related pair, so we can do this by acting as if the true probability distribution for the negative samples are zeros.


This code is licensed under CC-BY-NC 4.0.


In part adapted from poincare-embeddings


Hyperbolic (Poincare, Lorentz) Embeddings for TensorFlow




No releases published


No packages published