sequince.steps.constraints ========================== .. py:module:: sequince.steps.constraints .. autoapi-nested-parse:: Likelihood-constrained SMC steps and shell evidence bookkeeping. Attributes ---------- .. autoapisummary:: sequince.steps.constraints.LikelihoodThresholdSchedule Classes ------- .. autoapisummary:: sequince.steps.constraints.NestedSamplingLevel sequince.steps.constraints.LikelihoodConstrainedPrior sequince.steps.constraints.FixedLikelihoodThresholdSchedule sequince.steps.constraints.QuantileLikelihoodThresholdSchedule sequince.steps.constraints.WorstParticleLikelihoodThresholdSchedule sequince.steps.constraints.LikelihoodThresholdSelection sequince.steps.constraints.ShellEvidenceStep sequince.steps.constraints.LikelihoodThresholdWeighting sequince.steps.constraints.LogPriorMassStoppingCriterion Module Contents --------------- .. py:data:: LikelihoodThresholdSchedule .. py:class:: NestedSamplingLevel Diagnostics for a shell; prior volume is measured before discarding it. .. py:attribute:: output_key :type: ClassVar[str] :value: 'nested_sampling_level' .. py:attribute:: iteration :type: int .. py:attribute:: shell_lower_threshold :type: float .. py:attribute:: shell_upper_threshold :type: float | None .. py:attribute:: log_prior_volume :type: float .. py:attribute:: log_shell_expectation :type: float .. py:attribute:: log_evidence_increment :type: float .. py:attribute:: log_evidence :type: float .. py:attribute:: is_terminal :type: bool .. py:attribute:: n_surviving :type: int .. py:attribute:: survival_fraction :type: float .. py:class:: LikelihoodConstrainedPrior(log_prior_fn, log_likelihood_fn, *, inclusive = False) Bases: :py:obj:`sequince.target.Target` A static prior and likelihood with a context-dependent hard constraint. :param log_prior_fn: Return one log density per particle, accepting particles and optionally a context. The density functions must remain unchanged between levels; their cached values are reused when only the threshold changes. :type log_prior_fn: callable :param log_likelihood_fn: Return one log density per particle, accepting particles and optionally a context. The density functions must remain unchanged between levels; their cached values are reused when only the threshold changes. :type log_likelihood_fn: callable :param inclusive: Retain likelihoods equal to the threshold as well as those above it. :type inclusive: bool, optional .. py:attribute:: inclusive :value: False .. py:method:: evaluation_components(context) Components needed for a full density evaluation, when known. These are the components used to compute ``log_prob``, such as during MCMC. They need not include every component the target supports: ``log_increment`` is included only when the density itself requires it. Other components can still be requested explicitly through ``prepare_evaluation(components=...)``. When ``components=None``, preparation uses this declaration to complete a partial cache and retain only these components. Returning None preserves the default full-evaluation contract for custom targets. .. py:method:: evaluate(particles, context, *, components = None, evaluation = None) Evaluate or refresh named components of the target. .. py:method:: log_prob(particles, context, *, evaluation = None) Return the current target log density. .. py:class:: FixedLikelihoodThresholdSchedule Use a strictly increasing sequence of log-likelihood thresholds. Exhaustion records all remaining mass as a terminal shell. Positive infinity is also an explicit terminal threshold. .. py:attribute:: thresholds :type: collections.abc.Sequence[float] .. py:class:: QuantileLikelihoodThresholdSchedule Select an observed likelihood at the weighted quantile. Equal likelihoods are discarded together with a strict constraint. This can remove more than the requested fraction on a plateau. .. py:attribute:: quantile :type: float :value: 0.5 .. py:class:: WorstParticleLikelihoodThresholdSchedule Bases: :py:obj:`QuantileLikelihoodThresholdSchedule` Discard the lowest likelihood among particles with positive weight. .. py:class:: LikelihoodThresholdSelection(target, *, threshold_schedule = None, evidence_tolerance = None, log_likelihood_upper_bound = None) Bases: :py:obj:`sequince.steps.base.SMCStep` Select a threshold or finalize using an estimated remaining-evidence ratio. Schedules must implement ``schedule(log_likelihoods, state, context)`` and return a float or scalar array. ``StopIteration`` finalizes the remaining shell in eager/uncompiled execution; other exceptions propagate. Compiled schedules must be pure, JAX traceable, and use positive infinity to finalize rather than raising data-dependent exceptions or converting arrays to host scalars. Fixed and weighted-quantile schedules support both paths. ``evidence_tolerance`` compares the current estimate X * E[L] with the accumulated evidence. It is a stopping heuristic, not a rigorous bound on unobserved modes. Supply a known log_likelihood_upper_bound to use X * Lmax instead (X itself is estimated), or disable it for fixed-schedule experiments. .. py:attribute:: target .. py:attribute:: schedule .. py:attribute:: evidence_tolerance :value: None .. py:attribute:: log_likelihood_upper_bound :value: None .. py:method:: validate_functional_configuration(config, state) Reject unsupported NS-SMC pipelines before functional initialization. .. py:method:: initialize_functional_metadata(state, metadata) Return metadata with fields required by ``apply_functional``. .. py:method:: initialize_functional_state_and_context(state, context) Return shape-complete inputs for ``apply_functional``. Steps whose functional output adds array leaves should initialize matching leaves here so one compiled signature can be reused from the first iteration onward. .. py:method:: validate_functional_state_and_context(state, context) Validate numerical values at initialization and iteration boundaries. .. py:method:: apply_functional(state, context, random_state) Apply a functional step to particle step. This returns the updated state, context, next random state, and any additional outputs. This method is intended for use in functional SMC iterations where the random state is explicitly threaded through the computation. .. py:method:: apply(state, context, rng) .. py:class:: ShellEvidenceStep(target, *, store_shell_particles = True) Bases: :py:obj:`sequince.steps.base.SMCStep` Integrate a disjoint likelihood shell and optionally retain its particles. .. py:attribute:: target .. py:attribute:: store_shell_particles :value: True .. py:method:: apply_functional(state, context, random_state) Apply a functional step to particle step. This returns the updated state, context, next random state, and any additional outputs. This method is intended for use in functional SMC iterations where the random state is explicitly threaded through the computation. .. py:method:: apply(state, context, rng) .. py:class:: LikelihoodThresholdWeighting(target) Bases: :py:obj:`sequince.steps.base.SMCStep` Normalize survivor weights and accumulate constrained-prior mass. .. py:attribute:: target .. py:method:: apply_functional(state, context, random_state) Apply a functional step to particle step. This returns the updated state, context, next random state, and any additional outputs. This method is intended for use in functional SMC iterations where the random state is explicitly threaded through the computation. .. py:method:: apply(state, context, rng) .. py:class:: LogPriorMassStoppingCriterion(min_log_prior_volume, target, *, store_shell_particles = True) Bases: :py:obj:`sequince.steps.base.SMCStep` Finalize the remaining shell when prior mass falls below the given limit. Unlike the original prototype, stopping includes the surviving particles' evidence and posterior contributions before requesting an immediate stop. .. py:attribute:: minimum .. py:attribute:: shell .. py:method:: apply_functional(state, context, random_state) Apply a functional step to particle step. This returns the updated state, context, next random state, and any additional outputs. This method is intended for use in functional SMC iterations where the random state is explicitly threaded through the computation. .. py:method:: apply(state, context, rng)