aspire.samplers.smc.base

aspire.samplers.smc.base#

Attributes#

logger

DEFAULT_BETA_TOLERANCE

Exceptions#

BetaScheduleError

Unspecified run-time error.

Classes#

SMCSampler

Base class for Sequential Monte Carlo samplers.

NumpySMCSampler

SMCSampler that maps samples and log probabilities to NumPy arrays for

Module Contents#

aspire.samplers.smc.base.logger[source]#
aspire.samplers.smc.base.DEFAULT_BETA_TOLERANCE = 1e-08[source]#
exception aspire.samplers.smc.base.BetaScheduleError[source]#

Bases: RuntimeError

Unspecified run-time error.

class aspire.samplers.smc.base.SMCSampler(log_likelihood, log_prior, dims, prior_flow, xp, dtype=None, parameters=None, rng=None, preconditioning_transform=None)[source]#

Bases: aspire.samplers.mcmc.MCMCSampler

Base class for Sequential Monte Carlo samplers.

Parameters:

  • log_likelihood (Callable) – The log likelihood function.

  • log_prior (Callable) – The log prior function.

  • dims (int) – The number of dimensions.

  • prior_flow (Flow) – The prior flow.

  • xp (Callable) – The array API backend.

  • dtype (Any | str | None, optional) – The data type for the samples, by default None.

  • parameters (list[str] | None, optional) – The parameter names, by default None.

  • rng (np.random.Generator | ArrayRNG | None, optional) – The random number generator, by default None.

  • preconditioning_transform (Callable | None, optional) – The preconditioning transform, by default None.

rng[source]#
property target_efficiency[source]#
current_target_efficiency(beta)[source]#

Get the current target efficiency based on beta.

Parameters:

beta (float)

Return type:

float

determine_beta(samples, beta, beta_step, min_beta_step, max_beta_step=1.0, beta_tolerance=DEFAULT_BETA_TOLERANCE)[source]#

Determine the next beta value.

Parameters:

  • samples (SMCSamples) – The current samples.

  • beta (float) – The current beta value.

  • beta_step (float) – The fixed beta step size if not adaptive.

  • min_beta_step (float) – The minimum beta step size.

  • max_beta_step (float) – The maximum beta step size.

  • beta_tolerance (float) – Tolerance when checking for beta convergence.

Returns:

  • beta (float) – The new beta value.

  • min_beta_step (float) – The new minimum beta step size if adaptive_min_beta_step is True.

Raises:

BetaScheduleError – If adaptive beta is enabled and the determined beta does not increase from the previous beta.

Return type:

tuple[float, float]

sample(n_samples, n_steps=None, adaptive=True, min_beta_step=None, max_beta_step=None, max_n_steps=None, target_efficiency=0.5, target_efficiency_rate=1.0, n_final_samples=None, checkpoint_callback=None, checkpoint_every=None, checkpoint_file_path=None, resume_from=None, store_sample_history=True, beta_tolerance=DEFAULT_BETA_TOLERANCE)[source]#

Sample using the SMC sampler.

Parameters:

  • n_samples (int) – The number of samples (particles) to use in the SMC sampler.

  • n_steps (int, optional) – The number of SMC iterations to perform. Must be specified if adaptive=False. Default is None.

  • adaptive (bool, optional) – Whether to adaptively determine the beta schedule. Default is True.

  • min_beta_step (float, optional) – The minimum beta step size when using adaptive beta. Default is None, which means no minimum step size.

  • max_beta_step (float, optional) – The maximum beta step size when using adaptive beta. Default is None, which means no maximum step size.

  • max_n_steps (int, optional) – The maximum number of SMC iterations to perform when using adaptive beta. Default is None, which means no maximum.

  • target_efficiency (float or tuple, optional) – The target sample efficiency (ESS / n_samples) to aim for at each SMC iteration. Can be a single float in (0, 1) or a tuple of two floats specifying a range to adapt between. Default is 0.5.

  • target_efficiency_rate (float, optional) – When using a tuple for target_efficiency, this controls the rate at which the target efficiency adapts from the first value to the second value as beta increases. Default is 1.0 (linear adaptation).

  • n_final_samples (int, optional) – If specified, the number of final samples to produce after the SMC iterations. If not specified, the number of final samples will be the same as n_samples. Default is None.

  • checkpoint_callback (callable, optional) – A callback function to call with a checkpoint dictionary at regular intervals during sampling. Default is None (no checkpointing).

  • checkpoint_every (int, optional) – The number of iterations between checkpoints when using checkpoint callback. Default is None, which means no regular checkpointing.

  • checkpoint_file_path (str, optional) – If using checkpoint_callback, this can be used to specify a file path to save checkpoints to. Default is None.

  • resume_from (str, bytes, or dict, optional) – If specified, this can be used to resume sampling from a previous checkpoint. Can be a file path, bytes object, or checkpoint dictionary. Default is None (start from scratch).

  • store_sample_history (bool, optional) – Whether to store the history of samples at each iteration in self.history.sample_history. Default is True.

  • beta_tolerance (float, optional) – Tolerance for determining convergence of beta when using adaptive beta. Default is given by DEFAULT_BETA_TOLERANCE.

Returns:

final_samples – The final samples after running the SMC sampler, with log evidence and log evidence error estimates.

Return type:

SMCSamples

Raises:

ValueError – If both n_steps is None and adaptive is False, or if target_efficiency is not in (0, 1) when a float, or if target_efficiency tuple is not valid, or if log probabilities contain NaN values.

config_dict(include_sample_calls='last')[source]#

Returns a dictionary with the configuration of the sampler.

Parameters:

include_sample_calls (bool | str, optional) – Whether to include the sample calls in the configuration. Default is True. If True, and if the sampler has a sample method with a calls attribute, the calls will be included in the config under the key “sample_calls”. If this fails for any reason, a warning will be logged and the sample calls will be omitted.

Return type:

dict

abstractmethod mutate(particles)[source]#
log_prob(z, beta=None)[source]#

Compute the log probability of the samples.

Input samples are in the transformed space.

build_checkpoint_state(samples, iteration, beta)[source]#

Prepare a serializable checkpoint payload for the sampler state.

Parameters:
Return type:

dict

restore_from_checkpoint(source)[source]#

Restore sampler state from a checkpoint source.

Parameters:

source (str | bytes | dict)

Return type:

tuple[aspire.samples.SMCSamples, float, int]

class aspire.samplers.smc.base.NumpySMCSampler(log_likelihood, log_prior, dims, prior_flow, xp, dtype=None, parameters=None, preconditioning_transform=None)[source]#

Bases: SMCSampler

SMCSampler that maps samples and log probabilities to NumPy arrays for compatibility with numpy-only samplers

log_prob(z, beta=None)[source]#

Compute the log probability of the samples.

Input samples are in the transformed space.