Add install instructions and examples

.github/workflows/python-package-conda.yml

@@ -1,26 +1,33 @@
-name: Python Package using Conda
+name: Setup and run tests
 
-on: [push]
+on:
+  push:
+    branches: [ "main", "dev"]
+  pull_request:
+    branches: [ "main", "dev" ]
+  workflow_dispatch:
 
 jobs:
-  build-linux:
+  build:
+
     runs-on: ubuntu-latest
     strategy:
-      max-parallel: 5
+      fail-fast: false
+      matrix:
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.10
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v3
       with:
-        python-version: '3.10'
+        python-version: ${{ matrix.python-version }}
     - name: Add conda to system path
       run: |
         # $CONDA is an environment variable pointing to the root of the miniconda directory
         echo $CONDA/bin >> $GITHUB_PATH
     - name: Install dependencies
       run: |
-        # conda env update --file environment.yml --name base
         pip install -r requirements.txt
     - name: Lint with flake8
       run: |

README.md

@@ -31,6 +31,19 @@ print(log_prob.shape)  # (100,)
 print(x_new.shape)  # (50, 3)
 ```
 
+We provide more examples [here](examples/README.md).
+
+## Installing
+
+We support Python versions 3.7 and upwards.
+
+Install via git:
+```python
+git clone https://github.com/davidnabergoj/normalizing-flows.git
+cd normalizing-flows
+pip install -r requirements.txt
+```
+
 ## Brief background
 
 A normalizing flow (NF) is a flexible distribution, defined as a bijective transformation of a simple statistical

examples/README.md

@@ -0,0 +1,46 @@
+# Examples
+
+We provide minimal working examples on how to perform various common tasks with normalizing flows.
+We use Real NVP as an example, but you can replace it with any other bijection from `normalizing_flows.bijections`.
+
+## Training a normalizing flow on a fixed dataset
+```python
+import torch
+from normalizing_flows import Flow
+from normalizing_flows.bijections import RealNVP
+
+torch.manual_seed(0)
+
+# We support arbitrary event and batch shapes
+event_shape = (2, 3)
+batch_shape = (5, 7)
+x_train = torch.randn(size=(*batch_shape, *event_shape))
+
+bijection = RealNVP(event_shape=event_shape)
+flow = Flow(bijection)
+
+flow.fit(x_train, show_progress=True)
+```
+
+## Computing the log determinant of the Jacobian transformation given a Flow
+```python
+import torch
+from normalizing_flows import Flow
+from normalizing_flows.bijections import RealNVP
+
+torch.manual_seed(0)
+
+batch_shape = (5, 7)
+event_shape = (2, 3)
+x = torch.randn(size=(*batch_shape, *event_shape))
+z = torch.randn(size=(*batch_shape, *event_shape))
+
+bijection = RealNVP(event_shape=event_shape)
+flow = Flow(bijection)
+
+_, log_det_forward = flow.bijection.forward(x)
+# log_det_forward.shape == batch_shape
+
+_, log_det_inverse = flow.bijection.inverse(z)
+# log_det_inverse.shape == batch_shape
+```