Docs

README.rst

@@ -0,0 +1,62 @@
+Implicit Reparametrization Trick
+==========
+
+|test| |codecov| |docs|
+
+.. |test| image:: https://github.com/intsystems/ProjectTemplate/workflows/test/badge.svg
+    :target: https://github.com/intsystems/ProjectTemplate/tree/master
+    :alt: Test status
+
+.. |codecov| image:: https://img.shields.io/codecov/c/github/intsystems/ProjectTemplate/master
+    :target: https://app.codecov.io/gh/intsystems/ProjectTemplate
+    :alt: Test coverage
+
+.. |docs| image:: https://github.com/intsystems/ProjectTemplate/workflows/docs/badge.svg
+    :target: https://intsystems.github.io/implicit-reparameterization-trick/
+    :alt: Docs status
+
+Description
+==========
+
+This repository implements an educational project for the Bayesian Multimodeling course. It implements algorithms for sampling from various distributions, using the implicit reparameterization trick.
+
+Scope
+==========
+
+We plan to implement the following distributions in our library:
+
+- `Gaussian normal distribution`
+- `Dirichlet distribution (Beta distributions)`
+- `Sampling from a mixture of distributions`
+- `Sampling from the Student's t-distribution`
+- `Sampling from an arbitrary factorized distribution`
+
+Stack
+==========
+
+We plan to inherit from the torch.distribution.Distribution class, so we need to implement all the methods that are present in that class.
+
+Usage
+==========
+
+In this example, we demonstrate the application of our library using a Variational Autoencoder (VAE) model, where the latent layer is modified by a normal distribution.::
+
+    import torch.distributions.implicit as irt
+    params = Encoder(inputs)
+    gauss = irt.Normal(*params)
+    deviated = gauss.rsample()
+    outputs = Decoder(deviated)
+
+In this example, we demonstrate the use of a mixture of distributions using our library.::
+
+    import irt
+    params = Encoder(inputs)
+    mix = irt.Mixture([irt.Normal(*params), irt.Dirichlet(*params)])
+    deviated = mix.rsample()
+    outputs = Decoder(deviated)
+
+Links
+==========
+
+- `LinkReview <https://github.com/intsystems/implitic-reparametrization-trick/blob/main/linkreview.md>`_
+- `Plan of project <https://github.com/intsystems/implitic-reparametrization-trick/blob/main/planning.md>`_

doc/source/conf.py

@@ -15,7 +15,7 @@
 
 sys.path.insert(0, os.path.abspath('../../src/'))
 
-from mylib import __version__
+from irt import __version__
 
 
 # -- Project information -----------------------------------------------------
@@ -32,17 +32,13 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-=======
-
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 
               'sphinx.ext.intersphinx', 'sphinx.ext.todo',
               'sphinx.ext.ifconfig', 'sphinx.ext.viewcode',
               'sphinx.ext.inheritance_diagram',
               'sphinx.ext.autosummary', 'sphinx.ext.mathjax',
               'sphinx_rtd_theme']
 
-=======
-
 autodoc_mock_imports = ["numpy", "scipy", "sklearn", "torch"]
 
 # Add any paths that contain templates here, relative to this directory.

doc/source/info.rst

@@ -1 +1 @@
-.. include:: ../../README.md
+.. include:: ../../README.rst

doc/source/installation.rst

@@ -1 +1 @@
-.. include:: ../../src/README.md
+.. include:: ../../src/README.rst

src/README.md → src/README.rst

@@ -13,9 +13,13 @@ Installing by using PyPi
 
 Install
 -------
+.. code-block:: bash
+
 	git clone https://github.com/Intelligent-Systems-Phystech/implicit-reparameterization-trick.git /tmp/implicit-reparameterization-trick
 	python3 -m pip install /tmp/implicit-reparameterization-trick/src/
 
 Uninstall
 ---------
+.. code-block:: bash
+
 	python3 -m pip uninstall irt

src/irt/distributions.py

@@ -1,98 +1,26 @@
 import torch
+from torch.distributions import Distribution
 
-class torch.distributions.Distribution:
-	'''
-	The abstract base class for probability distributions, which we inherit from. These methods are implied
-	to be implemented for each subclass.
-	'''
-	def __init__(batch_shape=torch.Size([]), event_shape=torch.Size([])):
-		'''
-		Basic constructer of distribution.
-		'''
-
-	@property
-	def arg_constraints():
-		'''
-		Returns a dictionary from argument names to Constraint objects that should
-		be satisfied by each argument of this distribution. Args that are not tensors need not appear
-		in this dict.
-		'''
-
-	def cdf(value):
-		'''
-		Returns the cumulative density/mass function evaluated at value.
-		'''
-
-	def entropy():
-		'''
-		Returns entropy of distribution, batched over batch_shape.
-		'''
+class Normal(Distribution):
+    def __init__(self, loc, scale):
+        self.loc = loc
+        self.scale = scale
 
-	def enumerate_support(expand=True):
-		'''
-		Returns tensor containing all values supported by a discrete distribution. The result will
-		enumerate over dimension 0, so the shape of the result will be (cardinality,) + batch_shape
-		+ event_shape (where event_shape = () for univariate distributions).
-		'''
-
-	@property
-	def mean(expand=True):
-		'''
-		Returns mean of the distributio.
-		'''
+    def transform(self, z):
+        return (z - self.loc) / self.scale
+
+    def d_transform_d_z(self):
+        return 1 / self.scale
 
-	@property
-	def mode(expand=True):
-		'''
-		Returns mean of the distributio.
-		'''
-	def perplexity():
-		'''
-		Returns perplexity of distribution, batched over batch_shape.
-		'''
-
-	def rsample(sample_shape=torch.Size([])):
-		'''
-		Generates a sample_shape shaped sample or sample_shape shaped batch of samples if the distribution
-		parameters are batched.
-		'''
+    def sample(self):
+        return torch.normal(self.loc, self.scale).detach()
 
-	def sample(sample_shape=torch.Size([])):
-		'''
-		Generates a sample_shape shaped sample or sample_shape shaped batch of reparameterized samples
-		if the distribution parameters are batched.
-		'''
+    def rsample(self):
+        x = self.sample()
 
-class torch.distributions.implicit.Normal(Distribution):
-	'''
-	A Gaussian distribution class with backpropagation capability for the rsample function through IRT.
-	'''
-	def __init__(mean_matrix, covariance_matrix=None):
-		pass
+        transform = self.transform(x)
 
-class torch.distributions.implicit.Dirichlet(Distribution):
-	'''
-	A Dirichlet distribution class with backpropagation capability for the rsample function through IRT.
-	'''
-	def __init__(concentration, validate_args=None):
-		pass
-
-class torch.distributions.implicit.Mixture(Distribution):
-	'''
-	A Mixture of distributions class with backpropagation capability for the rsample function through IRT.
-	'''
-	def __init__(distributions : List[Distribution]):
-		pass
+        surrogate_x = - transform / self.d_transform_d_z().detach()
 
-class torch.distributions.implicit.Student(Distribution):
-	'''
-	A Student's distribution class with backpropagation capability for the rsample function through IRT.
-	'''
-	def __init__():
-		pass
-
-class torch.distributions.implicit.Factorized(Distribution):
-	'''
-	A class for an arbitrary factorized distribution with backpropagation capability for the rsample
-	function through IRT.
-	'''
+        # Replace gradients of x with gradients of surrogate_x, but keep the value.
+        return x + (surrogate_x - surrogate_x.detach())