added paper

paper/README.md

@@ -0,0 +1,12 @@
+# JOSS submission paper
+
+To compile run
+
+```bash
+cd paper
+docker run --rm \
+    --volume $PWD:/data \
+    --user $(id -u):$(id -g) \
+    --env JOURNAL=joss \
+    openjournals/inara
+```

paper/paper.bib

@@ -0,0 +1,136 @@
+@inbook{pytorch,
+author = {Paszke, Adam and Gross, Sam and Massa, Francisco and Lerer, Adam and Bradbury, James and Chanan, Gregory and Killeen, Trevor and Lin, Zeming and Gimelshein, Natalia and Antiga, Luca and Desmaison, Alban and K\"{o}pf, Andreas and Yang, Edward and DeVito, Zach and Raison, Martin and Tejani, Alykhan and Chilamkurthy, Sasank and Steiner, Benoit and Fang, Lu and Bai, Junjie and Chintala, Soumith},
+title = {PyTorch: An Imperative Style, High-Performance Deep Learning Library},
+year = {2019},
+publisher = {Curran Associates Inc.},
+address = {Red Hook, NY, USA},
+abstract = {Deep learning frameworks have often focused on either usability or speed, but not both. PyTorch is a machine learning library that shows that these two goals are in fact compatible: it provides an imperative and Pythonic programming style that supports code as a model, makes debugging easy and is consistent with other popular scientific computing libraries, while remaining efficient and supporting hardware accelerators such as GPUs.In this paper, we detail the principles that drove the implementation of PyTorch and how they are reflected in its architecture. We emphasize that every aspect of PyTorch is a regular Python program under the full control of its user. We also explain how the careful and pragmatic implementation of the key components of its runtime enables them to work together to achieve compelling performance. We demonstrate the efficiency of individual subsystems, as well as the overall speed of PyTorch on several common benchmarks.},
+booktitle = {Proceedings of the 33rd International Conference on Neural Information Processing Systems},
+articleno = {721},
+numpages = {12}
+}
+
+@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}
+}
+
+@article{normflows, 
+  author = {Vincent Stimper and David Liu and Andrew Campbell and Vincent Berenz and Lukas Ryll and Bernhard Schölkopf and José Miguel Hernández-Lobato}, 
+  title = {normflows: A PyTorch Package for Normalizing Flows}, 
+  journal = {Journal of Open Source Software}, 
+  volume = {8},
+  number = {86}, 
+  pages = {5361}, 
+  publisher = {The Open Journal}, 
+  doi = {10.21105/joss.05361}, 
+  url = {https://doi.org/10.21105/joss.05361}, 
+  year = {2023}
+} 
+
+@inproceedings{gradabm,
+  title = {Differentiable Agent-Based Epidemiology},
+  booktitle = {Proceedings of the 2023 International Conference on Autonomous Agents and Multiagent Systems},
+  author = {Chopra, Ayush and Rodr{\'i}guez, Alexander and Subramanian, Jayakumar and {Quera-Bofarull}, Arnau and Krishnamurthy, Balaji and Prakash, B. Aditya and Raskar, Ramesh},
+  year = {2023},
+  series = {{{AAMAS}} '23},
+  pages = {1848--1857},
+  publisher = {{International Foundation for Autonomous Agents and Multiagent Systems}},
+  address = {{Richland, SC}},
+  abstract = {Mechanistic simulators are an indispensable tool for epidemiology to explore the behavior of complex, dynamic infections under varying conditions and navigate uncertain environments. Agent-based models (ABMs) are an increasingly popular simulation paradigm that can represent the heterogeneity of contact interactions with granular detail and agency of individual behavior. However, conventional ABM frameworks not differentiable and present challenges in scalability; due to which it is non-trivial to connect them to auxiliary data sources. In this paper, we introduce GradABM: a scalable, differentiable design for agent-based modeling that is amenable to gradient-based learning with automatic differentiation. GradABM can quickly simulate million-size populations in few seconds on commodity hardware, integrate with deep neural networks and ingest heterogeneous data sources. This provides an array of practical benefits for calibration, forecasting, and evaluating policy interventions. We demonstrate the efficacy of GradABM via extensive experiments with real COVID-19 and influenza datasets.},
+  isbn = {978-1-4503-9432-1},
+  keywords = {automatic differentiation,computational epidemiology,deep neural networks,differentiable agent-based modeling}
+}
+
+@article{hep,
+  title={Differentiable programming in high-energy physics},
+  author={Baydin, At{\i}l{\i}m G{\"u}nes and NYU, Kyle Cranmer and Feickert, Matthew and Gray, Lindsey and Heinrich, Lukas and NYU, Alexander Held and Neubauer, Andrew Melo Vanderbilt Mark and Pearkes, Jannicke and Simpson, Nathan and Smith, Nick and others},
+  year={2020}
+}
+
+@article{ii,
+  title={Indirect inference},
+  author={Gourieroux, Christian and Monfort, Alain and Renault, Eric},
+  journal={Journal of applied econometrics},
+  volume={8},
+  number={S1},
+  pages={S85--S118},
+  year={1993},
+  publisher={Wiley Online Library}
+}
+
+@article{smm,
+  title={Applying the method of simulated moments to estimate a small agent-based asset pricing model},
+  author={Franke, Reiner},
+  journal={Journal of Empirical Finance},
+  volume={16},
+  number={5},
+  pages={804--815},
+  year={2009},
+  publisher={Elsevier}
+}
+
+@article{mala,
+  title={Exponential convergence of Langevin distributions and their discrete approximations},
+  author={Roberts, Gareth O and Tweedie, Richard L},
+  journal={Bernoulli},
+  pages={341--363},
+  year={1996},
+  publisher={JSTOR}
+}
+
+@article{hmc,
+  title={Hybrid monte carlo},
+  author={Duane, Simon and Kennedy, Anthony D and Pendleton, Brian J and Roweth, Duncan},
+  journal={Physics letters B},
+  volume={195},
+  number={2},
+  pages={216--222},
+  year={1987},
+  publisher={Elsevier}
+}
+
+@article{bissiri,
+  title={A general framework for updating belief distributions},
+  author={Bissiri, Pier Giovanni and Holmes, Chris and Walker, Stephen G},
+  journal={Journal of the Royal Statistical Society: Series B (Statistical Methodology)},
+  volume={78},
+  number={5},
+  pages={1103},
+  year={2016},
+  publisher={Wiley-Blackwell}
+}
+
+@article{gvi,
+  title={{An optimization-centric view on Bayes’ rule: Reviewing and generalizing variational inference}},
+  author={Knoblauch, Jeremias and Jewson, Jack and Damoulas, Theodoros},
+  journal={Journal of Machine Learning Research},
+  volume={23},
+  number={132},
+  pages={1--109},
+  year={2022}
+}
+
+@article{ai4abm,
+  title={Bayesian calibration of differentiable agent-based models},
+  author={Quera-Bofarull, Arnau and Chopra, Ayush and Calinescu, Anisoara and Wooldridge, Michael and Dyer, Joel},
+  journal={ICLR Workshop on AI for Agent-based Modelling},
+  year={2023}
+}
+
+@article{dae,
+  title={Some challenges of calibrating differentiable agent-based models},
+  author={Quera-Bofarull, Arnau and Dyer, Joel and Calinescu, Anisoara and Wooldridge, Michael},
+  journal={ICML Differentiable Almost Everything Workshop},
+  year={2023}
+}
+

paper/paper.md

@@ -0,0 +1,149 @@
+---
+title: 'BlackBIRDS: Black-Box Inference foR Differentiable Simulators'
+tags:
+  - Python
+  - Bayesian inference
+  - differentiable simulators
+  - variational inference
+  - Markov chain Monte Carlo
+authors:
+  - name: Arnau Quera-Bofarull
+    orcid: 0000-0001-5055-9863
+    equal-contrib: true
+    corresponding: true # (This is how to denote the corresponding author)
+    affiliation: "1, 2" # (Multiple affiliations must be quoted)
+  - name: Joel Dyer
+    orcid: 0000-0002-8304-8450
+    equal-contrib: true
+    corresponding: true # (This is how to denote the corresponding author)
+    affiliation: "1, 2"
+  - name: Anisoara Calinescu
+    orcid: 0000-0003-2082-734X
+    affiliation: 1
+  - name: Michael Wooldridge
+    orcid: 0000-0002-9329-8410
+    affiliation: 1
+affiliations:
+ - name: Department of Computer Science, University of Oxford, UK
+   index: 1
+ - name: Institute for New Economic Thinking, University of Oxford, UK
+   index: 2
+date: 14 July 2023
+bibliography: paper.bib
+
+# Optional fields if submitting to a AAS journal too, see this blog post:
+# https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing
+#aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it.
+#aas-journal: Astrophysical Journal <- The name of the AAS journal.
+---
+
+# Summary
+
+`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` [@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`, @normflows) to provide this broad functionality.
+
+# Statement of need
+
+Across scientific disciplines and application domains, simulation is
+used extensively as a means to studying complex mathematical models of real-world
+systems. A simulation-based approach to modelling such systems provides the
+modeller with significant benefits, permitting them to specify their model in the
+way that they believe most faithfully represents the true data-generating
+process and relieving them from concerns regarding the mathematical tractability
+of the resulting model. However, this additional flexibility comes at a price:
+the resulting model can be too complex to easily perform optimisation and
+inference tasks on the corresponding simulator, which in many cases necessitates 
+the use of approximate, simulation-based inference and optimisation methods to perform
+these tasks inexactly.
+
+The complicated and black-box nature of many simulation models can present a
+significant barrier to the successful deployment of these simulation-based inference 
+and optimisation techniques. Consequently, there has been increasing interest within
+various scientific communities in constructing *differentiable* simulation models (see e.g. @hep; @gradabm): 
+simulation models for which the gradient of the model output with respect to the
+model's input parameters can be easily obtained. The primary motivation for this is
+that access to this additional information, which captures the sensitivity of the
+output of the simulator to changes in the input, can enable the use of more efficient 
+simulation-based optimisation and inference procedures, helping to reduce the total runtime of such 
+algorithms, their overall consumption of valuable computational resources, and their 
+concomitant financial and environmental costs.
+
+To this end, `BlackBIRDS` was designed to provide researchers with easy access to a
+set of parameter inference methods that exploit the gradient information provided by
+differentiable simulators. The package provides support for a variety of approaches to
+gradient-assisted parameter inference, including:
+
+- Simulated Minimum Distance (SMD, see e.g. @ii; @smm), in which parameter
+  point estimates $\hat{\boldsymbol{\theta}}$ are obtained as
+
+  \begin{equation}
+      \hat{\boldsymbol{\theta}} 
+      = 
+      \arg \min_{\boldsymbol{\theta} \in \boldsymbol{\Theta}} {
+        \ell(\boldsymbol{\theta}, \mathbf{y})
+      },
+  \end{equation}
+  where $\boldsymbol{\theta}$ are the simulator's parameters, which take values in some
+  set $\boldsymbol{\Theta}$, and $f$ is a loss function capturing the compatibility between
+  the observed data $\mathbf{y}$ and the simulator's behaviour at parameter vector 
+  $\boldsymbol{\theta}$;
+- Markov chain Monte Carlo (MCMC), in which samples from a parameter posterior 
+
+    \begin{equation}
+        \pi(\boldsymbol{\theta} \mid \mathbf{y}) \propto e^{-\ell(\boldsymbol{\theta}, \mathbf{y})} \pi(\boldsymbol{\theta})
+    \end{equation}
+
+  corresponding to a choice of loss function $\ell$ and a prior density $\pi$ over $\boldsymbol{\Theta}$ 
+  are generated by executing a Markov chain on $\boldsymbol{\Theta}$. Currently, support is 
+  provided for Metropolis-adjusted Langevin Dynamics [@mala], although nothing prevents
+  the inclusion of additional 
+  gradient-assisted MCMC algorithms such as Hmailtonian Monte Carlo [@hmc];
+- Variational Inference (VI), in which a parameteric approximation $q^*$ to the
+  intractable posterior is obtained by solving the following optimisation problem over a
+  variational family $\mathcal{Q}$:
+
+  \begin{equation}
+    q^* = \arg\min_{q \in \mathcal{Q}} {
+            \mathbb{E}_{q}\left[ -\ell(\boldsymbol{\theta}, \mathbf{y})\right]
+            + \mathbb{E}_{q}\left[\log\frac{q(\boldsymbol{\theta})}{\pi(\boldsymbol{\theta})}\right]
+    }
+    \end{equation}
+  where $\ell$ is defined as above and $\pi$ is a prior density over $\boldsymbol{\Theta}$.
+
+The package is written such that the user is free to specify their choice of $\ell$ and $\pi$ (in the
+case of Bayesian methods), under the constraint that both choices are differentiable with respect to
+$\boldsymbol{\theta}$. This allows the user to target a wide variety of parameter point estimators, 
+and both classical and generalised (see e.g. @bissiri; @gvi) posteriors. We provide a
+number of [tutorials](https://www.arnau.ai/blackbirds/) demonstrating (a) how to implement a simulator
+in a differentiable framework in PyTorch and (b) how to apply the different parameter inference methods
+supported by `BlackBIRDS` to these differentiable simulators. Our package provides the user with flexible
+posterior density estimators with the use of normalising flows, and has already been used in scientific
+research to calibrate differentiable simulators, such as [@ai4abm; @dae], and in forthcoming publications
+yet to be announced publicly. We envisage that `BlackBIRDS` will further assist researchers in various fields
+to construct and experiment with differentiable implementations of mathematical simulation models.
+
+# Features
+
+- User-friendly and flexible API. Simulated Minimum Distance only requires the loss 
+  function $\ell$ and the optimiser to use, while in the case of MCMC (resp. VI), only the loss $\ell$, the prior 
+  density, and the MCMC method (resp. posterior approximator) must be specified. However, additional arguments
+  can be provided to straightforwardly specify hyperparameters of the method.
+- Multi-GPU parallelisation support with MPI.
+- Support for both forward-mode and reverse-mode auto-differentiation.
+- Continuous integration and unit tests.
+
+# Acknowledgements
+
+This research was supported by a UKRI AI World Leading Researcher Fellowship awarded to Wooldridge (grant EP/W002949/1). 
+M. Wooldridge and A. Calinescu acknowledge funding from Trustworthy AI - Integrating Learning, Optimisation and Reasoning 
+([TAILOR](https://tailor-network.eu/)), a project funded by European Union Horizon2020 research and innovation program 
+under Grant Agreement 952215.
+
+# References