Metadata-Version: 2.5
Name: mcsamplers
Version: 2026.9.4
Summary: Monte-Carlo samplers for gravitational-wave parameter estimation: nested sampling and MCMC
Project-URL: Homepage, https://gitlab.com/vaishakp/parameter-estimation
Project-URL: Bug Tracker, https://gitlab.com/vaishakp/parameter-estimation/-/issues
Author-email: Vaishak Prasad <vaishakprasad@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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.11
Requires-Dist: corner
Requires-Dist: h5py
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: psutil
Requires-Dist: scipy
Requires-Dist: sympy
Requires-Dist: tqdm
Requires-Dist: waveformtools
Provides-Extra: opt
Requires-Dist: pytest; extra == 'opt'
Requires-Dist: schwimmbad; extra == 'opt'
Description-Content-Type: text/markdown

# mcsamplers

Monte-Carlo stochastic samplers for gravitational-wave parameter estimation:
nested sampling and MCMC, built around a small `Model` base class that you
subclass with your own likelihood.

```bash
pip install mcsamplers
```

Requires Python 3.11+.

## The `Model` contract

Everything here works against one abstraction. Subclass `Model`, implement
`evaluate_logliklihood`, and the reduced-coordinate machinery comes with it:
the samplers explore the unit cube `[0, 1]^ndim`, and `Model` maps those
points onto your physical priors before calling you.

```python
import numpy as np
from mcsamplers.model import Model

class Gaussian(Model):
    def evaluate_logliklihood(self, parameters):
        return -0.5 * float(np.sum(np.asarray(parameters) ** 2))

model = Gaussian(
    xdata=np.linspace(0, 1, 64),
    ydata=np.zeros(64),
    initial_guess=[0.5, 0.5],
    parameter_priors_dict={"a": [0.0, 2.0], "b": [-1.0, 1.0]},
)

# Unit cube in, physical parameters out: (0.5, 0.5) -> (1.0, 0.0)
model.evaluate_logliklihood_reduced(np.array([0.5, 0.5]))
```

Priors are uniform boxes given as `{name: [min, max]}`. `Model` also supplies
`evaluate_liklihood`, `ln_prior_probability`, `pushforward_samples` and the
pickle round trip the samplers use for checkpointing.

## Nested sampling

```python
from mcsamplers.nested.sampler import NestedSampler

sampler = NestedSampler(n_live=500, n_dim=2, n_iter=5000, Model=model)
sampler.run()

samples = sampler.posterior_samples
log_z = sampler.logevidence
```

New live points are drawn according to `random_sample_method`, one of
`prior`, `mcmc`, `random-distance` or `relative-centroid`. Runs can be
checkpointed and resumed with `restart=True` and `checkpoint_time_stamps`.

## MCMC

`mcsamplers.markov_chain.yumcee` is a Metropolis–Hastings sampler with
multiple walkers:

```python
from mcsamplers.markov_chain.yumcee import yumcee_run

samples = yumcee_run(loglik, iguess, ndim, nwalkers, nsteps, prop_sigma)
```

`yumcee_p` is a parallel variant intended to run across nodes, and
`yumcee_utils` holds autocorrelation, corner-plot and sample-statistics
helpers.

## Tests

```bash
pip install mcsamplers[opt]
pytest --pyargs mcsamplers.tests
```

## Status and caveats

This is research code — used in anger, but not hardened for general use. The
test suite pins the `Model` contract, not sampling correctness: the samplers
themselves have no numerical regression tests.

## Licence

MIT. See [LICENSE](LICENSE).
