Skip to main content

Black-Box Inference foR Differentiable Simulators.

Project description

codecov Docs Build and test package PyPI version License: MIT

BlackBIRDS is a Python package consisting of generically applicable, black-box inference methods for differentiable simulation models. It facilitates both (a) the differentiable implementation of simulation models by providing a common object-oriented framework for their implementation in PyTorch, and (b) the use of a variety of gradient-assisted inference procedures for these simulation models, allowing researchers to easily exploit the differentiable nature of their simulator in parameter estimation tasks. The package consists of both Bayesian and non-Bayesian inference methods, and relies on well-supported software libraries (e.g. normflows, Stimper et al. (2023)) to provide this broad functionality.

1. Installation

The easiest way to install Birds is to install it from the PyPI repository

pip install blackbirds

To get the latest development version, you can install it directly from git

pip install git+

2. Usage

Refer to the docs for examples and specific API usage. Here is a basic example:

import torch

from blackbirds.models.random_walk import RandomWalk
from import VI
from blackbirds.posterior_estimators import TrainableGaussian
from blackbirds.simulate import simulate_and_observe_model

# random walk model
rw = RandomWalk(n_timesteps=100)

# generate synthetic data to fit to
true_p = torch.logit(torch.tensor(0.25))
true_data = rw.observe([true_p])))

# define loss to minimize
class L2Loss:
    def __init__(self, model):
        self.model = model
        self.loss_fn = torch.nn.MSELoss()
    def __call__(self, params, data):
        observed_outputs = simulate_and_observe_model(self.model, params)
        return self.loss_fn(observed_outputs[0], data[0])

# initialize generalized variational inference
posterior_estimator = TrainableGaussian([0.], 1.0)
prior = torch.distributions.Normal(true_p + 0.2, 1)
optimizer = torch.optim.Adam(posterior_estimator.parameters(), 1e-2)
loss = L2Loss(rw)

vi = VI(loss,
        w = 0) # no regularization

# train the estimator, 1000, max_epochs_without_improvement=100)

3. Tests

To run the unit tests of the code, you need to have pytest installed,

pip install pytest pytest-cov

and run the command

pytest test

4. Contributing

See for the contribution guidelines.

5. Citation

    doi = {10.21105/joss.05776}, 
    url = {}, 
    year = {2023}, 
    publisher = {The Open Journal}, 
    volume = {8}, 
    number = {89}, 
    pages = {5776}, 
    author = {Arnau Quera-Bofarull and Joel Dyer and Anisoara Calinescu and J. Doyne Farmer and Michael Wooldridge}, 
    title = {BlackBIRDS: Black-Box Inference foR Differentiable Simulators}, 
    journal = {Journal of Open Source Software} }

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blackbirds-1.2.tar.gz (22.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page