Metadata-Version: 2.1
Name: harmonic
Version: 1.2.1
Summary: Python package for efficient Bayesian evidence computation
Home-page: https://github.com/astro-informatics/harmonic
Author: Jason D. McEwen, Christopher G. R. Wallis, Matthew A. Price, Matthew M. Docherty, Alicja Polanska & Contributors
Author-email: jason.mcewen@ucl.ac.uk
License: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
License-File: LICENSE_EXT.txt
Requires-Dist: numpy
Requires-Dist: setuptools==68.0.0
Requires-Dist: wheel==0.41.0
Requires-Dist: cython>=0.29.30
Requires-Dist: ipython>=8.4.0
Requires-Dist: jupyter>=1.0.0
Requires-Dist: scikit-learn>=1.1.1
Requires-Dist: scipy>=1.8.1
Requires-Dist: colorlog>=6.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm
Requires-Dist: jax
Requires-Dist: jaxlib
Requires-Dist: flax
Requires-Dist: distrax
Requires-Dist: cloudpickle
Requires-Dist: getdist

harmonic
========

.. image:: https://img.shields.io/badge/GitHub-harmonic-brightgreen.svg?style=flat
    :target: https://github.com/astro-informatics/harmonic
.. image:: https://github.com/astro-informatics/harmonic/actions/workflows/python.yml/badge.svg
    :target: https://github.com/astro-informatics/harmonic/actions/workflows/python.yml
.. image:: https://readthedocs.org/projects/ansicolortags/badge/?version=latest
    :target: https://astro-informatics.github.io/harmonic/
.. image:: https://codecov.io/gh/astro-informatics/harmonic/branch/main/graph/badge.svg?token=1s4SATphHV
    :target: https://codecov.io/gh/astro-informatics/harmonic
.. image:: https://img.shields.io/badge/License-GPL-blue.svg
    :target: http://perso.crans.org/besson/LICENSE.html
.. image:: http://img.shields.io/badge/arXiv-2111.12720-orange.svg?style=flat
    :target: https://arxiv.org/abs/2111.12720
.. image:: http://img.shields.io/badge/arXiv-2207.04037-red.svg?style=flat
    :target: https://arxiv.org/abs/2207.04037
.. image:: http://img.shields.io/badge/arXiv-2307.00048-red.svg?style=flat
    :target: https://arxiv.org/abs/2307.00048


**Python package to efficiently compute the learnt harmonic mean estimator of the Bayesian evidence**


``harmonic`` is an open source, well tested and documented Python implementation of the *learnt harmonic mean estimator* (`McEwen et al. 2021 <https://arxiv.org/abs/2111.12720>`_) to compute the marginal likelihood (Bayesian evidence), required for Bayesian model selection.

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 <https://github.com/dfm/emcee>`_ code implementing the affine invariant sampler of `Goodman & Weare (2010) <https://cims.nyu.edu/~weare/papers/d13.pdf>`_.

Basic usage is highlighted in this `interactive demo <https://colab.research.google.com/github/astro-informatics/harmonic/blob/main/notebooks/basic_usage.ipynb>`_. 

Documentation
-------------

Comprehensive  `documentation for harmonic <https://astro-informatics.github.io/harmonic/>`_ is available.

Attribution
-----------

Please cite `McEwen et al. (2021) <https://arxiv.org/abs/2111.12720>`_ if this code package has been of use in your project. 

A BibTeX entry for the paper is:

.. code-block:: 

     @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) <https://arxiv.org/abs/2207.04037>`_ if this code has been of use in a simulation-based inference project.

A BibTeX entry for the paper is:

.. code-block::

     @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}
     }

.. code-block::

     @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}
     }

License
-------

``harmonic`` is released under the GPL-3 license (see `LICENSE.txt <https://github.com/astro-informatics/harmonic/blob/main/LICENSE.txt>`_), subject to 
the non-commercial use condition (see `LICENSE_EXT.txt <https://github.com/astro-informatics/harmonic/blob/main/LICENSE_EXT.txt>`_)

.. code-block::

     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.
