Merge pull request #140 from torchkge-team/develop

Merge develop before 0.16 release.
torchkge-team · May 5, 2020 · e4874be · e4874be
2 parents 29019fb + 2412e81
commit e4874be
Show file tree

Hide file tree

Showing 51 changed files with 3,544 additions and 2,993 deletions.
diff --git a/README.rst b/README.rst
@@ -25,6 +25,16 @@ TorchKGE
 
 TorchKGE: Knowledge Graph embedding in Python and Pytorch.
 
+TorchKGE is a Python module for knowledge graph (KG) embedding relying solely on Pytorch. This package provides
+researchers and engineers with a clean and efficient API to design and test new models. It features a KG data structure,
+simple model interfaces and modules for negative sampling and model evaluation. Its main strength is a highly efficient
+evaluation module for the  link prediction task,  a central application of KG embedding. It has been observed to be up
+to five times faster than `Ampligraph <https://docs.ampligraph.org/>`_ and twenty-four times faster than
+`OpenKE <https://github.com/thunlp/OpenKE>`_. Various KG embedding models are also already implemented. Special
+attention has been paid to code efficiency and simplicity, documentation and API consistency. It is distributed using
+PyPI under BSD license.
+
+A paper will be out soon !
 
 * Free software: BSD license
 * Documentation: https://torchkge.readthedocs.io.
diff --git a/docs/history.rst b/docs/history.rst
@@ -2,6 +2,19 @@
 History
 =======
 
+0.16.0 (2020-04-27)
+-------------------
+* Redefinition of the models' API (simplified interfaces, renamed LP methods and added get_embeddings method)
+* Implementation of the new API for all models
+* TorusE implementation fixed
+* TransD reimplementation to avoid matmul usage (costly in back-propagation)
+* Added feature to negative samplers to generate several negative samples from each fact. Those can be fed directly to
+  the models.
+* Added some wrappers for training to utils module.
+* Progress bars now make the most of tqdm's possibilities
+* Code reformatting
+* Docstrings update
+
 0.15.5 (2020-04-23)
 -------------------
 * Defined a new homemade and simpler DataLoader class.

diff --git a/docs/index.rst b/docs/index.rst
@@ -15,10 +15,9 @@ Welcome to TorchKGE' s documentation!
    :caption: Reference:
 
    reference/models
-   reference/sampling
    reference/evaluation
+   reference/sampling
    reference/data
-   reference/dataloader
    reference/utils
 
 

diff --git a/docs/reference/data.rst b/docs/reference/data.rst
@@ -4,14 +4,14 @@
 Data Structure
 *******************
 
-.. currentmodule:: torchkge.data
+.. currentmodule:: torchkge.data_structures
 
 Knowledge Graph
 ---------------
-.. autoclass:: torchkge.data.KnowledgeGraph.KnowledgeGraph
+.. autoclass:: torchkge.data_structures.KnowledgeGraph
     :members:
 
 Small KG
 --------
-.. autoclass:: torchkge.data.KnowledgeGraph.SmallKG
+.. autoclass:: torchkge.data_structures.SmallKG
     :members:
diff --git a/docs/reference/dataloader.rst b/docs/reference/dataloader.rst
diff --git a/docs/reference/evaluation.rst b/docs/reference/evaluation.rst
@@ -6,10 +6,10 @@ Evaluation
 
 Link Prediction
 ---------------
-.. autoclass:: torchkge.evaluation.LinkPrediction.LinkPredictionEvaluator
+.. autoclass:: torchkge.evaluation.link_prediction.LinkPredictionEvaluator
     :members:
 
 Triplet Classification
 ----------------------
-.. autoclass:: torchkge.evaluation.TripletClassification.TripletClassificationEvaluator
+.. autoclass:: torchkge.evaluation.triplet_classification.TripletClassificationEvaluator
     :members:
diff --git a/docs/reference/models.rst b/docs/reference/models.rst
@@ -13,64 +13,69 @@ Model
 
 TranslationalModels
 -------------------
-.. autoclass:: torchkge.models.interfaces.TranslationalModel
+.. autoclass:: torchkge.models.interfaces.TranslationModel
    :members:
 
 Translational Models
 ====================
 
 TransE
 ------
-.. autoclass:: torchkge.models.TranslationModels.TransEModel
+.. autoclass:: torchkge.models.translation.TransEModel
    :members:
 
 TransH
 ------
-.. autoclass:: torchkge.models.TranslationModels.TransHModel
+.. autoclass:: torchkge.models.translation.TransHModel
    :members:
 
 TransR
 ------
-.. autoclass:: torchkge.models.TranslationModels.TransRModel
+.. autoclass:: torchkge.models.translation.TransRModel
    :members:
 
 TransD
 ------
-.. autoclass:: torchkge.models.TranslationModels.TransDModel
+.. autoclass:: torchkge.models.translation.TransDModel
+   :members:
+
+TorusE
+------
+.. autoclass:: torchkge.models.translation.TorusEModel
    :members:
 
 Bilinear Models
 ===============
 
 RESCAL
 ------
-.. autoclass:: torchkge.models.BilinearModels.RESCALModel
+.. autoclass:: torchkge.models.bilinear.RESCALModel
    :members:
 
 DistMult
 --------
-.. autoclass:: torchkge.models.BilinearModels.DistMultModel
+.. autoclass:: torchkge.models.bilinear.DistMultModel
    :members:
 
 HolE
 ----
-.. autoclass:: torchkge.models.BilinearModels.HolEModel
+.. autoclass:: torchkge.models.bilinear.HolEModel
    :members:
 
 ComplEx
 -------
-.. autoclass:: torchkge.models.BilinearModels.ComplExModel
+.. autoclass:: torchkge.models.bilinear.ComplExModel
    :members:
 
 ANALOGY
 -------
-.. autoclass:: torchkge.models.BilinearModels.AnalogyModel
+.. autoclass:: torchkge.models.bilinear.AnalogyModel
    :members:
 
 Deep Models
 ===========
 
 ConvKB
 ------
-.. autoclass:: torchkge.models.DeepModels.ConvKBModel
+.. autoclass:: torchkge.models.deep.ConvKBModel
    :members:
diff --git a/docs/reference/sampling.rst b/docs/reference/sampling.rst
@@ -7,15 +7,15 @@ Negative Sampling
 
 Uniform negative sampler
 ------------------------
-.. autoclass:: torchkge.sampling.NegativeSampling.UniformNegativeSampler
+.. autoclass:: torchkge.sampling.UniformNegativeSampler
    :members:
 
 Bernoulli negative sampler
 --------------------------
-.. autoclass:: torchkge.sampling.NegativeSampling.BernoulliNegativeSampler
+.. autoclass:: torchkge.sampling.BernoulliNegativeSampler
    :members:
 
 Positional negative sampler
 ---------------------------
-.. autoclass:: torchkge.sampling.NegativeSampling.PositionalNegativeSampler
+.. autoclass:: torchkge.sampling.PositionalNegativeSampler
    :members:
diff --git a/docs/reference/utils.rst b/docs/reference/utils.rst
@@ -6,6 +6,16 @@ Utils
 
 .. currentmodule:: torchkge.utils
 
+Datasets loaders
+----------------
+
+.. autofunction:: torchkge.utils.datasets.load_fb13
+.. autofunction:: torchkge.utils.datasets.load_fb15k
+.. autofunction:: torchkge.utils.datasets.load_fb15k237
+.. autofunction:: torchkge.utils.datasets.load_wn18
+.. autofunction:: torchkge.utils.datasets.load_wikidatasets
+
+
 Dissimilarities
 ---------------
 .. autofunction:: torchkge.utils.dissimilarities.l1_dissimilarity
@@ -21,10 +31,9 @@ Losses
 .. autoclass:: torchkge.utils.losses.LogisticLoss
     :members:
 
-
-Operations
-----------
-
-.. autofunction:: torchkge.utils.operations.get_mask
-.. autofunction:: torchkge.utils.operations.get_rolling_matrix
-.. autofunction:: torchkge.utils.operations.get_rank
+Training wrappers
+-----------------
+.. autoclass:: torchkge.utils.training.TrainDataLoader
+    :members:
+.. autoclass:: torchkge.utils.training.Trainer
+    :members:
diff --git a/docs/tutorials/hole.rst b/docs/tutorials/hole.rst
diff --git a/docs/tutorials/linkprediction.rst b/docs/tutorials/linkprediction.rst
@@ -4,16 +4,19 @@ Link Prediction
 
 To evaluate a model on link prediction::
 
-    from torchkge.data.DataLoader import load_fb15k
+    from torch import cuda
+    from torchkge.models import TransEModel
+    from torchkge.utils.datasets import load_fb15k
     from torchkge.evaluation import LinkPredictionEvaluator
 
     _, _, kg_test = load_fb15k()
 
-    # Assume the variable `model` was trained on the training subset of FB15k
-    global model
+    model = TransEModel(100, pre_trained='fb15k')
+    if cuda.is_available():
+        model.cuda()
 
     # Link prediction evaluation on test set.
     evaluator = LinkPredictionEvaluator(model, kg_test)
-    evaluator.evaluate(batch_size=512, k_max=10)
-    evaluator.evaluate(k=10)
+    evaluator.evaluate(b_size=32, k_max=10)
     evaluator.print_results()
+
diff --git a/docs/tutorials/training.rst b/docs/tutorials/training.rst
@@ -1,8 +1,10 @@
 Model Training
 **************
 
-Training a model with TorchKGE is pretty standard. Here are two examples of models being trained on FB15k.
+Here are two examples of models being trained on FB15k.
 
 .. include:: transe.rst
 
-.. include:: hole.rst
+.. include:: transe_wrappers.rst
+
+.. include:: transe_early_stopping.rst