sequince.steps.weighting ======================== .. py:module:: sequince.steps.weighting Attributes ---------- .. autoapisummary:: sequince.steps.weighting.IncrementFn sequince.steps.weighting.BetaSchedule sequince.steps.weighting.TargetESSRatio sequince.steps.weighting.logger Classes ------- .. autoapisummary:: sequince.steps.weighting.IncrementalWeighting sequince.steps.weighting.LogLikelihoodWeighting sequince.steps.weighting.BaseTemperedStep sequince.steps.weighting.TemperedWeighting sequince.steps.weighting.FixedTemperedWeighting sequince.steps.weighting.AdaptiveTemperedWeighting Functions --------- .. autoapisummary:: sequince.steps.weighting.evolving_target_ess_ratio Module Contents --------------- .. py:data:: IncrementFn .. py:data:: BetaSchedule .. py:data:: TargetESSRatio .. py:data:: logger .. py:function:: evolving_target_ess_ratio(start, end, *, rate = 1.0, max_beta = 1.0) Return a power-law schedule for an evolving target ESS ratio. The schedule evolves from ``start`` to ``end`` as the beta moves from zero to ``max_beta``. Betas outside that interval are clipped to the corresponding endpoint. Values of ``rate`` greater than one delay the transition, while values below one accelerate it. :param start: Target ESS ratio at zero beta; must be in ``(0, 1]``. :param end: Target ESS ratio at ``max_beta``; must be in ``(0, 1]``. :param rate: Positive exponent controlling the rate of transition. :param max_beta: Positive beta at which the schedule reaches ``end``. .. py:class:: IncrementalWeighting(log_increment_fn, *, normalize_after = True) Bases: :py:obj:`sequince.steps.base.SMCStep` Apply a complete sequential-target log-weight increment. A callable can have signature ``(particles,)`` or ``(particles, context)``. A ``SequentialTarget`` supplies its current complete increment and participates in evaluation caching. .. py:method:: initialize_functional_state_and_context(state, context) Attach a cached target evaluation before functional compilation. .. py:method:: apply(state, context, rng) .. py:class:: LogLikelihoodWeighting(log_increment_fn, *, normalize_after = True) Bases: :py:obj:`IncrementalWeighting` Backward-compatible name for callable likelihood increments. .. py:class:: BaseTemperedStep(log_increment_fn, *, normalize_after = True, refresh_components = ()) Bases: :py:obj:`sequince.steps.base.SMCStep` Base class for tempered weighting steps. This provides common functionality for tempering steps that apply log-weight increments scaled by a beta schedule (e.g. ``TemperedWeighting`` and ``AdaptiveTemperedWeighting``). It does not implement the logic for determining the beta schedule itself, which is left to subclasses. .. py:method:: initialize_functional_state_and_context(state, context) Attach a cached target evaluation before functional compilation. .. py:method:: evaluate_log_increment(state, context) Return increments and attach a missing target evaluation. .. py:method:: initialize_metadata(state, context) Initialize metadata related to tempering. .. py:method:: initialize_functional_metadata(state, metadata) Initialize fixed-shape tempering metadata on the array backend. .. py:method:: apply(state, context, rng) :abstractmethod: .. py:class:: TemperedWeighting(log_increment_fn, beta_schedule, *, normalize_after = True, clip_beta = None, refresh_components = ()) Bases: :py:obj:`BaseTemperedStep` Apply tempering by scaling log-weight increments with a beta schedule. Both the increment callable and the beta schedule accept the current ``StepContext`` when they require it. .. py:method:: apply(state, context, rng) .. py:class:: FixedTemperedWeighting(log_increment_fn, *, beta_increment, max_beta = 1.0, normalize_after = True, refresh_components = ()) Bases: :py:obj:`BaseTemperedStep` Apply fixed beta increments up to ``max_beta`` (default 1.0). Clip the final increment and request a stop after that iteration. The maximum must be finite and positive. .. py:method:: apply(state, context, rng) .. py:method:: apply_functional(state, context, random_state) Apply fixed tempering without host scalar conversions. .. py:class:: AdaptiveTemperedWeighting(log_increment_fn, *, target_ess_ratio = 0.7, max_beta = 1.0, min_delta = 0.0001, max_delta = None, normalize_after = True, max_bisection_iter = 30, criterion = 'ess', refresh_components = ()) Bases: :py:obj:`BaseTemperedStep` Adaptively choose the next beta using an ESS-like target. The beta increment is chosen such that the effective sample size (ESS) ratio after weighting, or the conditional ESS (CESS) ratio implied by a proposed increment, reaches the specified target value (``target_ess_ratio``), up to the maximum beta (``max_beta``). If the maximum beta is reached while advancing the schedule, the SMC run is requested to stop after the current iteration finishes. :param log_increment_fn: A callable or ``TemperedTarget`` providing log-weight increments. :param target_ess_ratio: The target ESS ratio (ESS / n) to achieve after weighting, or a callable that returns the target for the current beta. The callable may optionally also accept the current ``StepContext``. Each resolved target must be in the interval (0, 1]. :param max_beta: The maximum beta to reach; once this beta is reached, the SMC run is requested to stop after the current iteration. :param min_delta: The minimum beta increment to apply at each step. :param max_delta: Optional maximum beta increment to apply at each step. :param normalize_after: Whether to normalize the particle weights after updating. :param max_bisection_iter: The maximum number of bisection iterations to perform when finding the beta increment. :param criterion: Criterion used when selecting the beta increment. ``"ess"`` targets the ESS ratio after weighting. ``"cess"`` targets the conditional ESS ratio induced by the proposed incremental weights. .. rubric:: Notes The returned particle state and current step context record ``beta``, ``delta_beta``, ``ess_ratio``, and ``cess_ratio``. Active updates also record ``target_ess_ratio``. .. py:method:: initialize_functional_metadata(state, metadata) Initialize fixed-shape adaptive tempering metadata. .. py:method:: apply(state, context, rng) .. py:method:: apply_functional(state, context, random_state) Apply adaptive tempering while explicitly threading random state.