Better README#3

[arashabzd]

Added a short usage section with a diagram of the API to README.md and two simple examples that show the general workflow of defining and training a conditional/unconditional flow.

[arturbekasov]

Thanks for taking the time to write this up. I think this is a good start for better documentation.

Before I can merge this, a few comments:

1. While useful, I think the diagram is somehwat too technical for a readme. I propose dropping it for now.
2. On other changes in the readme: I think most of the changes could be replaced with a short snippet of code of the form flow = Flow(transform, base_distribution), showing an example of how to create a transform and a base_distribution, and only then point to nflows.transformations and nflows.distributions as places where to find more transforms and distributions, and to examples for more examples.
3. In the notebooks: sub-classing the Flow class is a rather convoluted way to create a flow. It's much easier and much more concise to create a Flow instance with the desired transformation and base distribution (see 2.). Could this be updated?

[arashabzd]

Yes, sure. Notebooks got updated. About the code snippet, I'm not sure which specific transform to use since each transform has different parameters. Do you have any preferences?

[arturbekasov]

No need to get into transform parameters. This is what I have in mind:

To define a flow:

from nflows import transforms, distributions, flows

# Define an invertible transformation.
transform = transforms.CompositeTranform([
    transforms.AffineCouplingTransform(...),
    transforms.RandomPermutation(...)
])

# Define a base distribution.
base_distribution = distributions.StandardNormal(...)

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

To evaluate log probabilities of inputs:

log_prob = flow.log_prob(inputs)

To sample from the flow:

samples = flow.sample(num_samples=...)

[arturbekasov]

Yep, this looks good. See the last nitpick: happy to merge after it's fixed.

Any further improvements could be done outside of this PR.

Thanks!

[imurray]

@arashabzd thanks so much for contributing these docs and examples! It's appreciated. (And thanks @arturbekasov for shepherding the PR.)