aspire.samplers.smc.base ======================== .. py:module:: aspire.samplers.smc.base Attributes ---------- .. autoapisummary:: aspire.samplers.smc.base.logger aspire.samplers.smc.base.DEFAULT_BETA_TOLERANCE Exceptions ---------- .. autoapisummary:: aspire.samplers.smc.base.BetaScheduleError Classes ------- .. autoapisummary:: aspire.samplers.smc.base.SMCSampler aspire.samplers.smc.base.NumpySMCSampler Module Contents --------------- .. py:data:: logger .. py:data:: DEFAULT_BETA_TOLERANCE :value: 1e-08 .. py:exception:: BetaScheduleError Bases: :py:obj:`RuntimeError` Unspecified run-time error. .. py:class:: SMCSampler(log_likelihood, log_prior, dims, prior_flow, xp, dtype = None, parameters = None, rng = None, preconditioning_transform = None) Bases: :py:obj:`aspire.samplers.mcmc.MCMCSampler` Base class for Sequential Monte Carlo samplers. :param log_likelihood: The log likelihood function. :type log_likelihood: :py:class:`Callable` :param log_prior: The log prior function. :type log_prior: :py:class:`Callable` :param dims: The number of dimensions. :type dims: :py:class:`int` :param prior_flow: The prior flow. :type prior_flow: :py:class:`Flow` :param xp: The array API backend. :type xp: :py:class:`Callable` :param dtype: The data type for the samples, by default None. :type dtype: :py:class:`Any | str | None`, *optional* :param parameters: The parameter names, by default None. :type parameters: :py:class:`list[str] | None`, *optional* :param rng: The random number generator, by default None. :type rng: :py:class:`np.random.Generator | ArrayRNG | None`, *optional* :param preconditioning_transform: The preconditioning transform, by default None. :type preconditioning_transform: :py:class:`Callable | None`, *optional* .. py:attribute:: rng .. py:property:: target_efficiency .. py:method:: current_target_efficiency(beta) Get the current target efficiency based on beta. .. py:method:: determine_beta(samples, beta, beta_step, min_beta_step, max_beta_step = 1.0, beta_tolerance = DEFAULT_BETA_TOLERANCE) Determine the next beta value. :param samples: The current samples. :type samples: :py:class:`SMCSamples` :param beta: The current beta value. :type beta: :py:class:`float` :param beta_step: The fixed beta step size if not adaptive. :type beta_step: :py:class:`float` :param min_beta_step: The minimum beta step size. :type min_beta_step: :py:class:`float` :param max_beta_step: The maximum beta step size. :type max_beta_step: :py:class:`float` :param beta_tolerance: Tolerance when checking for beta convergence. :type beta_tolerance: :py:class:`float` :returns: * **beta** (:py:class:`float`) -- The new beta value. * **min_beta_step** (:py:class:`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. .. py:method:: 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) Sample using the SMC sampler. :param n_samples: The number of samples (particles) to use in the SMC sampler. :type n_samples: :py:class:`int` :param n_steps: The number of SMC iterations to perform. Must be specified if :code:`adaptive=False`. Default is None. :type n_steps: :py:class:`int`, *optional* :param adaptive: Whether to adaptively determine the beta schedule. Default is True. :type adaptive: :py:class:`bool`, *optional* :param min_beta_step: The minimum beta step size when using adaptive beta. Default is None, which means no minimum step size. :type min_beta_step: :py:class:`float`, *optional* :param max_beta_step: The maximum beta step size when using adaptive beta. Default is None, which means no maximum step size. :type max_beta_step: :py:class:`float`, *optional* :param max_n_steps: The maximum number of SMC iterations to perform when using adaptive beta. Default is None, which means no maximum. :type max_n_steps: :py:class:`int`, *optional* :param target_efficiency: 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. :type target_efficiency: :py:class:`float` or :py:class:`tuple`, *optional* :param target_efficiency_rate: 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). :type target_efficiency_rate: :py:class:`float`, *optional* :param n_final_samples: 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. :type n_final_samples: :py:class:`int`, *optional* :param checkpoint_callback: A callback function to call with a checkpoint dictionary at regular intervals during sampling. Default is None (no checkpointing). :type checkpoint_callback: :py:class:`callable`, *optional* :param checkpoint_every: The number of iterations between checkpoints when using checkpoint callback. Default is None, which means no regular checkpointing. :type checkpoint_every: :py:class:`int`, *optional* :param checkpoint_file_path: If using checkpoint_callback, this can be used to specify a file path to save checkpoints to. Default is None. :type checkpoint_file_path: :py:class:`str`, *optional* :param resume_from: 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). :type resume_from: :py:class:`str`, :py:class:`bytes`, or :py:class:`dict`, *optional* :param store_sample_history: Whether to store the history of samples at each iteration in :code:`self.history.sample_history`. Default is True. :type store_sample_history: :py:class:`bool`, *optional* :param beta_tolerance: Tolerance for determining convergence of beta when using adaptive beta. Default is given by :code:`DEFAULT_BETA_TOLERANCE`. :type beta_tolerance: :py:class:`float`, *optional* :returns: **final_samples** -- The final samples after running the SMC sampler, with log evidence and log evidence error estimates. :rtype: :py:class:`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. .. py:method:: config_dict(include_sample_calls = 'last') Returns a dictionary with the configuration of the sampler. :param include_sample_calls: 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. :type include_sample_calls: :py:class:`bool | str`, *optional* .. py:method:: mutate(particles) :abstractmethod: .. py:method:: log_prob(z, beta=None) Compute the log probability of the samples. Input samples are in the transformed space. .. py:method:: build_checkpoint_state(samples, iteration, beta) Prepare a serializable checkpoint payload for the sampler state. .. py:method:: restore_from_checkpoint(source) Restore sampler state from a checkpoint source. .. py:class:: NumpySMCSampler(log_likelihood, log_prior, dims, prior_flow, xp, dtype=None, parameters=None, preconditioning_transform=None) Bases: :py:obj:`SMCSampler` SMCSampler that maps samples and log probabilities to NumPy arrays for compatibility with numpy-only samplers .. py:method:: log_prob(z, beta=None) Compute the log probability of the samples. Input samples are in the transformed space.