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.

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.

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

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:

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

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.