Merge pull request #7 from intsystems/dev

v1.1.0

.github/workflows/docs.yml

@@ -37,7 +37,7 @@ jobs:
           
       - name: Build Docs
         run: |
-          sphinx-build -b html docs public
+          sphinx-build -b html docs/source public
           touch public/.nojekyll
           
       - name: Deploy 🚀

.github/workflows/pypi.yml

@@ -1,4 +1,4 @@
-name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
+name: Publish Python 🐍 distribution 📦 to PyPI
 
 on: push
 
@@ -90,28 +90,4 @@ jobs:
       run: >-
         gh release upload
         '${{ github.ref_name }}' dist/**
-        --repo '${{ github.repository }}'
-
-  publish-to-testpypi:
-    name: Publish Python 🐍 distribution 📦 to TestPyPI
-    needs:
-    - build
-    runs-on: ubuntu-latest
-
-    environment:
-      name: testpypi
-      url: https://test.pypi.org/p/relaxit
-
-    permissions:
-      id-token: write  # IMPORTANT: mandatory for trusted publishing
-
-    steps:
-    - name: Download all the dists
-      uses: actions/download-artifact@v4
-      with:
-        name: python-package-distributions
-        path: dist/
-    - name: Publish distribution 📦 to TestPyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        repository-url: https://test.pypi.org/legacy/
+        --repo '${{ github.repository }}'

README.md

@@ -52,9 +52,9 @@
 6. [Tests](https://github.com/intsystems/discrete-variables-relaxation/tree/main/tests)
 
 ## 💡 Motivation
-For lots of mathematical problems we need an ability to sample discrete random variables. 
-The problem is that due to continuos nature of deep learning optimization, the usage of truely discrete random variables is infeasible. 
-Thus we use different relaxation method. 
+For lots of mathematical problems we need an ability to sample discrete random variables.
+The problem is that due to continuous nature of deep learning optimization, the usage of truly discrete random variables is infeasible.
+Thus we use different relaxation methods. 
 One of them, [Concrete distribution](https://arxiv.org/abs/1611.00712) or [Gumbel-Softmax](https://arxiv.org/abs/1611.01144) (this is one distribution proposed in parallel by two research groups) is implemented in different DL packages. 
 In this project we implement different alternatives to it. 
 <div align="center">  
@@ -65,11 +65,11 @@ In this project we implement different alternatives to it.
 - [x] [Relaxed Bernoulli](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/GaussianRelaxedBernoulli.py), also see [📝 paper](http://proceedings.mlr.press/v119/yamada20a/yamada20a.pdf) 
 - [x] [Correlated relaxed Bernoulli](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/CorrelatedRelaxedBernoulli.py), also see [📝 paper](https://openreview.net/pdf?id=oDFvtxzPOx)
 - [x] [Gumbel-softmax TOP-K](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/GumbelSoftmaxTopK.py), also see [📝 paper](https://arxiv.org/pdf/1903.06059) 
-- [x] [Straight-Through Bernoulli](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/StraightThroughBernoulli.py), also see [📝 paper](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=62c76ca0b2790c34e85ba1cce09d47be317c7235) 
+- [x] [Straight-Through Bernoulli](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/StraightThroughBernoulli.py), also see [📝 paper](https://arxiv.org/abs/1910.02176) 
+- [x] [Stochastic Times Smooth](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/StochasticTimesSmooth.py), also see [📝 paper](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=62c76ca0b2790c34e85ba1cce09d47be317c7235) 
 - [x] [Invertible Gaussian](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/InvertibleGaussian.py) with [KL implemented](https://github.com/intsystems/discrete-variables-relaxation/blob/f398ebbbac703582de392bc33d89b55c6c99ea68/src/relaxit/distributions/kl.py#L7), also see [📝 paper](https://arxiv.org/abs/1912.09588)
 - [x] [Hard Concrete](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/HardConcrete.py), also see [📝 paper](https://arxiv.org/pdf/1712.01312) 
-- [x] [REINFORCE](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/CorrelatedRelaxedBernoulli.py), also see [📺 slides](http://www.cs.toronto.edu/~tingwuwang/REINFORCE.pdf)
-- [x] [Logit-Normal](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/LogisticNormalSoftmax.py) and [Laplace-form approximation of Dirichlet](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/approx.py), also see [ℹ️ wiki](https://en.wikipedia.org/wiki/Logit-normal_distribution) and [💻 stackexchange](https://stats.stackexchange.com/questions/535560/approximating-the-logit-normal-by-dirichlet) 
+- [x] [Logistic-Normal](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/LogisticNormalSoftmax.py) and [Laplace-form approximation of Dirichlet](https://github.com/intsystems/discrete-variables-relaxation/blob/main/src/relaxit/distributions/approx.py), also see [ℹ️ wiki](https://en.wikipedia.org/wiki/Logit-normal_distribution) and [💻 stackexchange](https://stats.stackexchange.com/questions/535560/approximating-the-logit-normal-by-dirichlet) 
 
 ## 🛠️ Install
 
@@ -116,13 +116,15 @@ print('sample.requires_grad:', sample.requires_grad)
 | ![Laplace Bridge](https://github.com/user-attachments/assets/ac5d5a71-e7d7-4ec3-b9ca-9b72d958eb41) | ![REINFORCE](https://gymnasium.farama.org/_images/acrobot.gif) | ![VAE](https://github.com/user-attachments/assets/937585c4-df84-4ab0-a2b9-ea6a73997793) |
 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/intsystems/discrete-variables-relaxation/blob/main/demo/laplace-bridge.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/intsystems/discrete-variables-relaxation/blob/main/demo/reinforce.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/intsystems/discrete-variables-relaxation/blob/main/demo/demo.ipynb) |
 
-For demonstration purposes, we divide our algorithms in three different groups. Each group relates to the particular demo code:
+For demonstration purposes, we divide our algorithms in three[^*] different groups. Each group relates to the particular demo code:
 - [Laplace bridge between Dirichlet and LogisticNormal distributions](https://github.com/intsystems/discrete-variables-relaxation/blob/main/demo/laplace-bridge.ipynb)
 - [REINFORCE](https://github.com/intsystems/discrete-variables-relaxation/blob/main/demo/reinforce.ipynb)
 - [Other relaxation methods](https://github.com/intsystems/discrete-variables-relaxation/blob/main/demo/demo.ipynb)
 
 We describe our demo experiments [here](https://github.com/intsystems/discrete-variables-relaxation/tree/main/demo).
 
+[^*]: We also implement REINFORCE algorithm as a *score function* estimator alternative for our relaxation methods that are inherently *pathwise derivative* estimators. This one is implemented only for demo experiments and is not included into the source code of package.
+
 ## 📚 Stack
 Some of the alternatives for GS were implemented in [pyro](https://docs.pyro.ai/en/dev/distributions.html), so we base our library on their codebase.
 

demo/README.md

@@ -1,5 +1,5 @@
 # Demo experiments code
-This repository contains our demo code for various experiments. The main demo code can be found in the notebook `demo/demo.ipynb`. Open the notebook and run the cells to see the demonstration in action. For additional experiments, refer to the section [Additional experiments](#experiments). Before starting any experiments, ensure you follow all the installation steps outlined in the [Installation](#installation) section.
+This repository contains our demo code for various experiments. The main demo code can be found in the notebook `demo.ipynb`. Open the notebook and run the cells to see the demonstration in action. For additional experiments, refer to the section [Additional experiments](#experiments). Before starting any experiments, ensure you follow all the installation steps outlined in the [Installation](#installation) section.
 
 ## Installation <a name="installation"></a>
 
@@ -27,33 +27,36 @@ For additional demo experiments, we have implemented Variational Autoencoders (V
 1. **Train and save the models:**
    To run the additional demo code with VAEs, you need to train all the models and save their results. Execute the following commands:
     ```bash
-    # VAE with Gaussian Bernoulli latent space
-    python vae_gaussian_bernoulli.py
-
     # VAE with Correlated Bernoulli latent space
     python vae_correlated_bernoulli.py
-
+
+    # VAE with Gaussian Bernoulli latent space
+    python vae_gaussian_bernoulli.py
+
+    # VAE with Gumbel-Softmax top-K latent space
+    python vae_gumbel_softmax_topk.py
+
     # VAE with Hard Concrete latent space
     python vae_hard_concrete.py
 
-    # VAE with Straight Through Bernoullii latent space
-    python vae_straight_through_bernoulli.py
-
     # VAE with Invertible Gaussian latent space
     python vae_invertible_gaussian.py
 
-    # VAE with Gumbel Softmax TopK latent space
-    python vae_gumbel_softmax_topk.py
+    # VAE with Stochastic Times Smooth latent space
+    python vae_stochastic_times_smooth.py
+
+    # VAE with Straight Through Bernoullii latent space
+    python vae_straight_through_bernoulli.py
     ```
 2. **View the results:**
-    After completing the training and testing of all the models, you can find the results of sampling and reconstruction methods in the directory `demo/results`.
+    After completing the training and testing of all the models, you can find the results of sampling and reconstruction methods in the directory `results`.
 
 Moreover, we conducted experiments with Laplace Bridge between LogisticNormal and Dirichlet distributions. We use two-side Laplace bridge to approximate:
-- Dirichlet using logisticNormal
-- LogisticNormal using Dirichlet
+- Dirichlet using Logistic-Normal
+- Logistic-Normal using Dirichlet
 
-These experiments aim to find the best parameters to make the distributions nearly identical on the simplex. The experiments can be found in the notebook `demo/laplace-bridge.ipynb`.
+These experiments aim to find the best parameters to make the distributions nearly identical on the simplex. The experiments can be found in the notebook `laplace-bridge.ipynb`.
 
-Furthermore, the Reinforce algorithm is applied in the [Acrobot environment](https://www.gymlibrary.dev/environments/classic_control/acrobot/). Detailed experiments can be viewed in the notebook `demo/reinforce.ipynb`. A script `demo/reinforce.py` can also be used for training.
+Furthermore, the Reinforce algorithm is applied in the [Acrobot environment](https://www.gymlibrary.dev/environments/classic_control/acrobot/). Detailed experiments can be viewed in the notebook `reinforce.ipynb`. A script `reinforce.py` can also be used for training.
 
 

demo/requirements.txt

@@ -1,11 +1,10 @@
-gym==0.26.2
-numpy==1.24.1
-pyro_ppl==1.9.1
-setuptools==65.5.0
-torch==2.5.1
-torchvision==0.20.1
-matplotlib==3.9.2
-networkx==3.3
-tqdm==4.66.5
-pillow==10.4.0
-relaxit==0.1.2
+gym>=0.26.2
+numpy>=1.24.1
+torchvision>=0.20.1
+matplotlib>=3.9.2
+networkx>=3.3
+tqdm>=4.66.5
+pillow>=10.4.0
+relaxit==1.0.1
+ftfy
+regex