Advanced API

MCMC Samplers

surmise.create_sampler(sampler, options)[source]

Construct a sampler function for direct use by surmise calibrators. The following example demonstrates its use.

sample_with_PTLMC = surmise.create_sampler("PTLMC", ptlmc_args)
results = sample_with_PTLMC(
    logpost_func=log_posterior,
    draw_func=draw_from_start_distribution,
    scipy_stats_rng=np.random.default_rng(RAND_SEED)
)

For typical use cases, samplers are created automatically under-the-hood on behalf of users. Therefore, there is generally no need to explicitly create or access samplers. This function is in the surmise public interface only as an advanced feature for use by developers and power users.

Todo

  • The current implementation prevents users from providing a custom sampler to calibrators. Consider allowing sampler to be a user-provided sampler function that we assume has the necessary interface. This function could then confirm that options is None or an empty dict and just pass that function along. If the calibrator interface is updated so that calling code must provide a sampler identifier, then that argument could also be setup in this same way.

Parameters:

  • sampler – Name of desired sampler offered by surmise

  • options – dict of sampler-specific arguments that fully characterize the desired sampler. Refer to the documentation of each sampler for more information.

Returns:

The desired sampler function.