Metadata-Version: 2.4
Name: bilby-laplace
Version: 0.2.0
Summary: Bilby sampler plugin: Laplace approximation with rejection/importance resampling
Author: Gregory Ashton
License-Expression: MIT
Project-URL: Homepage, https://github.com/GregoryAshton/bilby-laplace
Project-URL: Documentation, https://gregoryashton.github.io/bilby-laplace/
Project-URL: Source, https://github.com/GregoryAshton/bilby-laplace
Project-URL: Issues, https://github.com/GregoryAshton/bilby-laplace/issues
Project-URL: Changelog, https://github.com/GregoryAshton/bilby-laplace/blob/main/CHANGELOG.md
Keywords: bayesian inference,laplace approximation,bilby,gravitational waves
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bilby>=2.7
Requires-Dist: numpy
Requires-Dist: scipy>=1.15
Requires-Dist: pandas
Requires-Dist: tqdm
Provides-Extra: docs
Requires-Dist: mkdocs<2; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: pymdown-extensions; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

# bilby-laplace

A [Bilby](https://bilby-dev.github.io/bilby/) sampler plugin that estimates posteriors
via the **Laplace approximation** — a Gaussian fitted at the maximum a posteriori (MAP)
point using the Hessian of the log-posterior — followed by optional resampling to
correct for non-Gaussianity.

The method is fast, scales well to moderate dimensions, and produces asymptotically
exact posterior samples when the true posterior is close to Gaussian. It is
useful as a cheap cross-check against nested sampling results.

> **Documentation:** full guides, the configuration/API reference, and background on
> the method are at **<https://gregoryashton.github.io/bilby-laplace/>**.

Originally derived from [bilby PR #933](https://github.com/bilby-dev/bilby/pull/933).

## Installation

```bash
pip install bilby-laplace
```

Or from source:

```bash
git clone https://github.com/GregoryAshton/bilby-laplace
cd bilby-laplace
pip install -e .
```

Bilby discovers the sampler automatically via its plugin entry-point system — no
further configuration is needed.

## Quick start

```python
import bilby

result = bilby.run_sampler(
    likelihood=likelihood,
    priors=priors,
    sampler="laplace",
    outdir="outdir",
    label="my_run",
)

result.plot_corner()
print(result.posterior)
```

## Features

- Several resampling strategies to correct for non-Gaussianity: `rejection`,
  `importance`, `inprior`, `smc` (via [aspire](https://github.com/bilby-dev/aspire)),
  or none.
- Two covariance routes: the numerical Hessian (`fisher_method="hessian"`, any
  likelihood) or the genuine waveform Fisher matrix (`fisher_method="waveform"`, for
  gravitational-wave likelihoods).
- Supply a precomputed covariance via `sampling_cov` (e.g. from gwfast / GWFish).
- Multimodal posteriors via SMC with `n_modes > 1`.
- Laplace log-evidence always available; rejection and SMC add independent estimates.

See the [documentation](https://gregoryashton.github.io/bilby-laplace/) for the full list
of options and guidance on choosing between them.

## Examples

Runnable examples are in [`examples/`](https://github.com/GregoryAshton/bilby-laplace/tree/main/examples) (gaussian, rosenbrock, BBH, BNS).
Each has a `Makefile`:

```bash
cd examples/gaussian
make laplace
make compare
```

## Citing

If you use `bilby-laplace`, please cite the software release; citation metadata
is in [`CITATION.cff`](https://github.com/GregoryAshton/bilby-laplace/blob/main/CITATION.cff) (GitHub's "Cite this repository" button
reads it).

## License

MIT; see [`LICENSE`](https://github.com/GregoryAshton/bilby-laplace/blob/main/LICENSE).

## Documentation development

```bash
pip install -e ".[docs]"
mkdocs serve
```
