This package provides probability density functions to benchmark sampling and optimization algorithms. The name potentials is used as a reference to the negative log probability density function. The package is in the process of changing.
Synthetic examples include:
- Standard Gaussian
- Diagonal Gaussian (several variants)
- Block diagonal Gaussian (several variants)
- Full rank Gaussian (several variants)
- Gaussian mixture (several variants)
- Multimodal (several variants)
- Funnel (several variants)
- Banana
- Funana
- Rosenbrock
- Student's t
- Double well
- Phi^4 lattice field theory
Real-world examples include various model posteriors:
- Eight schools
- German credit
- Sparse German credit
- Radon (varying intercepts)
- Radon (varying slopes)
- Radon (varying intercepts and slopes)
- Synthetic item response theory
- Stochastic volatility model
The main components in the package are callable Potential objects.
They can be used to compute the negative unnormalized log probability density.
In most synthetic examples, Potential objects also provide a sample function which lets us draw true samples from their underlying distributions.
We provide an example for the funnel potential:
import torch
from potentials.synthetic.funnel import Funnel
torch.manual_seed(0)
# Create the potential object
potential = Funnel()
batch_shape = (50,)
# Randomly generate some input data
x = torch.randn(size=(*batch_shape, *potential.event_shape)) / 10
# Compute the potential value at input points
value = potential(x) # value.shape == (50,)
# Draw 50 samples from the underlying distribution
x_new = potential.sample(batch_shape) # x_new.shape == (50, 100)This package requires Python version 3.7 or greater.
Install the package directly from Github:
pip install git+https://github.com/davidnabergoj/potentials.git
To alternatively configure the package for local development, clone the repository and install it in editable mode:
git clone git@github.com:davidnabergoj/potentials.git
cd potentials
pip install -e .
Run the tests with:
pip install pytest
pytest -m "not local_only"
If you use this code in your work, kindly consider citing the accompanying paper:
BibTex entry:
@misc{nabergoj_nf_mcmc_evaluation_2024,
author = {Nabergoj, David and \v{S}trumbelj, Erik},
title = {Empirical evaluation of normalizing flows in {Markov} {Chain} {Monte} {Carlo}},
publisher = {arXiv},
month = dec,
year = {2024},
note = {arxiv:2412.17136}
}
This project is licensed under the MIT License. See LICENSE for details.