** Numerically Accurate Hyperbolic Embeddings Using Tiling-Based Models

**** Authors:
- [[http://www.cs.cornell.edu/~tyu/][Tao Yu]]
- [[http://www.cs.cornell.edu/~cdesa/][Christopher De Sa]]
[[file:H266.png]]

*** Introduction
This repo contains official code (learning part in PyTorch) and models for the NeurIPS 2019 paper,
[[http://papers.neurips.cc/paper/8476-numerically-accurate-hyperbolic-embeddings-using-tiling-based-models.pdf][Numerically Accurate Hyperbolic Embeddings Using Tiling-Based Models]].
We implemented our models under the same frame of [[https://github.com/facebookresearch/poincare-embeddings][Poincaré Embeddings for Learning Hierarchical Representations]],
which is licensed under =LICENSE= and [[https://creativecommons.org/licenses/by-nc/4.0/][CC-BY-NC 4.0]]. However, we preserve the
rights for commerical purpose of our tiling-based models.

** Installation
Clone this repository and run following commands
#+BEGIN_SRC sh
  git clone https://github.com/ydtydr/HyperbolicTiling_Learning.git
  cd HyperbolicTiling_Learning
  conda env create -f environment.yml
  source activate tiling
  python setup.py build_ext --inplace
#+END_SRC

** Dependencies
- Python 3 with NumPy
- PyTorch
- Scikit-Learn
- NLTK (to generate the WordNet data)

** Example: Embedding WordNet Mammals
First generate the transitive closure of data via
#+BEGIN_SRC sh
  cd wordnet
  python transitive_closure.py
#+END_SRC
This will generate the transitive closure of the full noun, verb hierarchy as well as of the mammals subtree of WordNet.
We also include the Gr-QC dataset in /wordnet/ folder.

To embed the mammals subtree in the reconstruction setting, go to the /root directory/ of
the project and run
#+BEGIN_SRC sh
  ./train-mammals.sh
#+END_SRC
This shell script includes the appropriate parameter settings for the mammals subtree. Similar scripts to learn embeddings
of Word nouns, Verbs and Gr-QC are located at =train-nouns.sh=, =train-verbs.sh=,
=train-grqc.sh=. These scripts contain the hyperparameters to reproduce the embeddings results in the paper with available
models: =Poincare=, =Lorentz=, =NLorentz=, =LTiling_rsgd=, =NLTiling_rsgd=, =LTiling_sgd= and =HTiling_rsgd=. Multithreaded async SGD training is also supported.

** References
If you use our code or wish to refer to our results, please use the following BibTex entry:
#+BEGIN_SRC bibtex
@incollection{yu2019numerically,
  title = {Numerically Accurate Hyperbolic Embeddings Using Tiling-Based Models},
  author = {Yu, Tao and De Sa, Christopher M},
  booktitle = {Proceedings of the 33rd Conference on Neural Information Processing Systems (NeurIPS 2019)},
  month = {Oct.},
  year = {2019}
}
#+END_SRC