nflows

nflows is a comprehensive collection of normalizing flows using PyTorch.

Installation

To install from PyPI:

pip install nflows

Usage

To define a flow:

from nflows import transforms, distributions, flows

# Define an invertible transformation.
transform = transforms.CompositeTransform([
    transforms.MaskedAffineAutoregressiveTransform(features=2, hidden_features=4),
    transforms.RandomPermutation(features=2)
])

# Define a base distribution.
base_distribution = distributions.StandardNormal(shape=[2])


# Combine into a flow.
flow = flows.Flow(transform=transform, distribution=base_distribution)

or use already implemented flow architectures:

from nflows.flows import MaskedAutoregressiveFlow, SimpleRealNVP

features=2
hidden_features=4

maf = MaskedAutoregressiveFlow(features=features, hidden_features=hidden_features)
rnvp = SimpleRealNVP(features=features, hidden_features=hidden_features)
nice = SimpleRealNVP(feautres=features, hidden_features=hidden_features, use_volumne_perserving=True)

To evaluate log probabilities of inputs:

log_prob = flow.log_prob(inputs)

To sample from the flow:

samples = flow.sample(num_samples)

Additional examples of the workflow are provided in examples folder.

Development

You can install all the dependencies using the environment.yml file to create a conda environment:

conda env create -f environment.yml

Alternatively, you can install via setup.py (the dev flag installs development and testing dependencies):

pip install -e ".[dev]"

Citing nflows

To cite the package:

@software{nflows,
  author       = {Conor Durkan and
                  Artur Bekasov and
                  Iain Murray and
                  George Papamakarios},
  title        = {{nflows}: normalizing flows in {PyTorch}},
  month        = nov,
  year         = 2020,
  publisher    = {Zenodo},
  version      = {v0.14},
  doi          = {10.5281/zenodo.4296287},
  url          = {https://doi.org/10.5281/zenodo.4296287}
}

The version number is intended to be the one from nflows/version.py. The year/month correspond to the date of the release. BibTeX entries for other versions could be found on Zenodo.

If you're using spline-based flows in particular, consider citing the Neural Spline Flows paper: [bibtex].

References

nflows is derived from bayesiains/nsf originally published with

C. Durkan, A. Bekasov, I. Murray, G. Papamakarios, Neural Spline Flows, NeurIPS 2019. [arXiv] [bibtex]

nflows has been used in

Conor Durkan, Iain Murray, George Papamakarios, On Contrastive Learning for Likelihood-free Inference, ICML 2020. [arXiv].

Artur Bekasov, Iain Murray, Ordering Dimensions with Nested Dropout Normalizing Flows. [arXiv].

Tim Dockhorn, James A. Ritchie, Yaoliang Yu, Iain Murray, Density Deconvolution with Normalizing Flows. [arXiv].

nflows is used by the conditional density estimation package pyknos, and in turn the likelihood-free inference framework sbi.