harmonic is an open source, well tested and documented Python implementation of the learnt harmonic mean estimator (McEwen et al. 2021) to compute the marginal likelihood (Bayesian evidence), required for Bayesian model selection.

For an accessible overview of the learnt harmonic mean estimator please see this Towards Data Science article.

While harmonic requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, harmonic works exceptionally well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. We therefore advocate use of harmonic with the popular emcee code implementing the affine invariant sampler of Goodman & Weare (2010).

Basic usage is highlighted in this interactive demo.

Brief installation instructions are given below (for further details see the full installation documentation).

The harmonic package can be installed by running

pip install harmonic

The harmonic package can also be installed from source by running

git clone https://github.com/astro-informatics/harmonic
cd harmonic

and running the install script, within the root directory, with one command

bash build_harmonic.sh

To check the install has worked correctly run the unit tests with

pytest 

To build the documentation from source run

cd docs && make html

Then open ./docs/_build/html/index.html in a browser.

Comprehensive documentation for harmonic is available.

Jason D. McEwen, Christopher G. R. Wallis, Matthew A. Price, Matthew M. Docherty, Alessio Spurio Mancini, Alicja Polanska.

Please cite McEwen et al. (2021) if this code package has been of use in your project.

A BibTeX entry for the paper is:

@article{harmonic, 
   author = {Jason~D.~McEwen and Christopher~G.~R.~Wallis and Matthew~A.~Price and Matthew~M.~Docherty},
    title = {Machine learning assisted {B}ayesian model comparison: learnt harmonic mean estimator},
  journal = {ArXiv},
   eprint = {arXiv:2111.12720},
     year = 2021
}

Please also cite Spurio Mancini et al. (2022) if this code has been of use in a simulation-based inference project.

A BibTeX entry for the paper is:

@article{spurio-mancini:harmonic_sbi,
   author   = {A.~Spurio Mancini and M.~M.~Docherty and M.~A.~Price and J.~D.~McEwen},
   doi      = {10.1093/rasti/rzad051},
   eprint   = {arXiv:2207.04037},
   journal  = {{RASTI}, in press},
   title    = {{B}ayesian model comparison for simulation-based inference},
   year     = {2023}
}

Please also cite Polanska et al. (2023) if using normalizing flow models.

A BibTeX entry for the paper is:

@inproceedings{polanska:harmonic_nfs_maxent,
   author    = {A.~Polanska and M.~A.~Price and A.~Spurio Mancini and J.~D.~McEwen},
   booktitle = {International Workshop on Bayesian Inference and Maximum Entropy Methods in Science and Engineering},
   eprint    = {arXiv:2307.00048},
   title     = {Learned harmonic mean estimation of the marginal likelihood with normalizing flows},
   year      = {2023}
}

harmonic is released under the GPL-3 license (see LICENSE.txt), subject to the non-commercial use condition (see LICENSE_EXT.txt)

harmonic
Copyright (C) 2021 Jason D. McEwen, Christopher G. R. Wallis, 
Matthew A. Price, Matthew M. Docherty, Alessio Spurio Mancini, 
Alicja Polanska & contributors

This program is released under the GPL-3 license (see LICENSE.txt), 
subject to a non-commercial use condition (see LICENSE_EXT.txt).

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.