Science Score: 36.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
✓Academic publication links
Links to: arxiv.org -
○Committers with academic emails
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (10.3%) to scientific vocabulary
Keywords
Repository
Normalizing flows in PyTorch
Basic Info
- Host: GitHub
- Owner: probabilists
- License: mit
- Language: Python
- Default Branch: master
- Homepage: https://zuko.readthedocs.io
- Size: 415 KB
Statistics
- Stars: 396
- Watchers: 12
- Forks: 30
- Open Issues: 5
- Releases: 5
Topics
Metadata Files
README.md
Zuko - Normalizing flows in PyTorch
Zuko is a Python package that implements normalizing flows in PyTorch. It relies as much as possible on distributions and transformations already provided by PyTorch. Unfortunately, the Distribution and Transform classes of torch are not sub-classes of torch.nn.Module, which means you cannot send their internal tensors to GPU with .to('cuda') or retrieve their parameters with .parameters(). Worse, the concepts of conditional distribution and transformation, which are essential for probabilistic inference, are impossible to express.
To solve these problems, zuko defines two concepts: the LazyDistribution and LazyTransform, which are any modules whose forward pass returns a Distribution or Transform, respectively. Because the creation of the actual distribution/transformation is delayed, an eventual condition can be easily taken into account. This design enables lazy distributions, including normalizing flows, to act like distributions while retaining features inherent to modules, such as trainable parameters. It also makes the implementations easy to understand and extend.
Acknowledgements
Zuko takes significant inspiration from nflows and Stefan Webb's work in Pyro and FlowTorch.
Installation
The zuko package is available on PyPI, which means it is installable via pip.
pip install zuko
Alternatively, if you need the latest features, you can install it from the repository.
pip install git+https://github.com/probabilists/zuko
Getting started
Normalizing flows are provided in the zuko.flows module. To build one, supply the number of sample and context features as well as the transformations' hyperparameters. Then, feeding a context $c$ to the flow returns a conditional distribution $p(x | c)$ which can be evaluated and sampled from.
```python import torch import zuko
Neural spline flow (NSF) with 3 sample features and 5 context features
flow = zuko.flows.NSF(3, 5, transforms=3, hidden_features=[128] * 3)
Train to maximize the log-likelihood
optimizer = torch.optim.Adam(flow.parameters(), lr=1e-3)
for x, c in trainset: loss = -flow(c).log_prob(x) # -log p(x | c) loss = loss.mean()
optimizer.zero_grad()
loss.backward()
optimizer.step()
Sample 64 points x ~ p(x | c*)
x = flow(c_star).sample((64,)) ```
Alternatively, flows can be built as custom Flow objects.
```python from zuko.flows import Flow, UnconditionalDistribution, UnconditionalTransform from zuko.flows.autoregressive import MaskedAutoregressiveTransform from zuko.distributions import DiagNormal from zuko.transforms import RotationTransform
flow = Flow( transform=[ MaskedAutoregressiveTransform(3, 5, hiddenfeatures=(64, 64)), UnconditionalTransform(RotationTransform, torch.randn(3, 3)), MaskedAutoregressiveTransform(3, 5, hiddenfeatures=(64, 64)), ], base=UnconditionalDistribution( DiagNormal, torch.zeros(3), torch.ones(3), buffer=True, ), ) ```
For more information, check out the documentation and tutorials at zuko.readthedocs.io.
Available flows
| Class | Year | Reference |
|:-------:|:----:|-----------|
| GMM | - | Gaussian Mixture Model |
| NICE | 2014 | Non-linear Independent Components Estimation |
| MAF | 2017 | Masked Autoregressive Flow for Density Estimation |
| NSF | 2019 | Neural Spline Flows |
| NCSF | 2020 | Normalizing Flows on Tori and Spheres |
| SOSPF | 2019 | Sum-of-Squares Polynomial Flow |
| NAF | 2018 | Neural Autoregressive Flows |
| UNAF | 2019 | Unconstrained Monotonic Neural Networks |
| CNF | 2018 | Neural Ordinary Differential Equations |
| GF | 2020 | Gaussianization Flows |
| BPF | 2020 | Bernstein-Polynomial Normalizing Flows |
Contributing
If you have a question, an issue or would like to contribute, please read our contributing guidelines.
Owner
- Name: The Probabilists
- Login: probabilists
- Kind: organization
- Email: theprobabilists@gmail.com
- Repositories: 1
- Profile: https://github.com/probabilists
A community for open probabilistic science.
GitHub Events
Total
- Create event: 3
- Release event: 1
- Issues event: 5
- Watch event: 72
- Issue comment event: 25
- Push event: 19
- Pull request review event: 6
- Pull request review comment event: 13
- Pull request event: 10
- Fork event: 11
Last Year
- Create event: 3
- Release event: 1
- Issues event: 5
- Watch event: 72
- Issue comment event: 25
- Push event: 19
- Pull request review event: 6
- Pull request review comment event: 13
- Pull request event: 10
- Fork event: 11
Committers
Last synced: 9 months ago
Top Committers
| Name | Commits | |
|---|---|---|
| François Rozet | f****t@o****m | 118 |
| Peter Steinbach | p****h@h****e | 2 |
| MArpogaus | 3****s | 2 |
| Felix Divo | 4****o | 2 |
| Simon Schnake | s****n@g****m | 1 |
| Dominik Strutz | 4****z | 1 |
| Alejandro Almodóvar | 4****s | 1 |
| Adrián Javaloy | a****y@g****m | 1 |
Committer Domains (Top 20 + Academic)
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 20
- Total pull requests: 32
- Average time to close issues: about 2 months
- Average time to close pull requests: about 1 month
- Total issue authors: 14
- Total pull request authors: 13
- Average comments per issue: 4.1
- Average comments per pull request: 2.81
- Merged pull requests: 22
- Bot issues: 0
- Bot pull requests: 0
Past Year
- Issues: 2
- Pull requests: 8
- Average time to close issues: about 17 hours
- Average time to close pull requests: 7 days
- Issue authors: 2
- Pull request authors: 5
- Average comments per issue: 1.5
- Average comments per pull request: 2.38
- Merged pull requests: 1
- Bot issues: 0
- Bot pull requests: 0
Top Authors
Issue Authors
- francois-rozet (4)
- arnauqb (2)
- MArpogaus (2)
- adrianjav (2)
- michaeldeistler (2)
- jmm34 (1)
- MouzaouiMatthieu (1)
- aalmodovares (1)
- felixdivo (1)
- dominik-strutz (1)
- chester-tan (1)
- Bill-Gots (1)
- emprice (1)
- simonschnake (1)
- velezbeltran (1)
Pull Request Authors
- francois-rozet (13)
- MArpogaus (6)
- psteinb (3)
- felixdivo (2)
- oduerr (2)
- Namgyu-Youn (2)
- dominik-strutz (2)
- valsdav (2)
- namgyu-youn (2)
- adrianjav (2)
- emprice (2)
- aalmodovares (1)
- simonschnake (1)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 1
-
Total downloads:
- pypi 7,536 last-month
- Total dependent packages: 3
- Total dependent repositories: 1
- Total versions: 28
- Total maintainers: 1
pypi.org: zuko
Normalizing flows in PyTorch
- Documentation: https://zuko.readthedocs.io/
- License: MIT License
-
Latest release: 1.4.1
published 9 months ago
Rankings
Maintainers (1)
Dependencies
- numpy >=1.20.0
- torch >=1.8.0
- actions/checkout v3 composite
- actions/setup-python v4 composite
- docutils ==0.19
- furo ==2023.3.27
- sphinx ==6.1.3