sequince.target =============== .. py:module:: sequince.target Attributes ---------- .. autoapisummary:: sequince.target.logger sequince.target.TargetComponentFn Classes ------- .. autoapisummary:: sequince.target.EvaluationCounts sequince.target.TargetEvaluation sequince.target.Target sequince.target.SequentialTarget sequince.target.TemperedTarget Module Contents --------------- .. py:data:: logger .. py:data:: TargetComponentFn .. py:class:: EvaluationCounts Backend-compatible counters for probabilistic model evaluations. The fields count work required to evaluate the log target density, log likelihood, log proposal, and log increment. Log-target work includes any refreshed target-density component, while log-likelihood work records only calls to ``log_likelihood``. Reusing cached components does not count again. .. py:attribute:: log_target_evaluations :type: Any :value: 0 .. py:attribute:: log_likelihood_evaluations :type: Any :value: 0 .. py:attribute:: log_proposal_evaluations :type: Any :value: 0 .. py:attribute:: log_increment_evaluations :type: Any :value: 0 .. py:method:: zeros(*, xp = None) :classmethod: Return zero counts, optionally as scalars from an array namespace. .. py:class:: TargetEvaluation Named, particle-aligned values evaluated by a target. .. py:attribute:: components :type: collections.abc.Mapping[str, sequince.typing.Array] .. py:attribute:: target_id :type: str | None :value: None .. py:attribute:: evaluation_key :type: collections.abc.Hashable | None :value: None .. py:property:: n_particles :type: int Number of particle-aligned entries in the evaluation. .. py:method:: validate_for(particles) Validate that this evaluation has one entry per supplied particle. .. py:method:: with_target(target_id, evaluation_key) Return this evaluation associated with a target state. .. py:method:: copy() Return a detached copy preserving array backends. .. py:method:: take(indices) Select particle evaluations using ancestor indices. .. py:method:: replace(indices, replacement) Return an evaluation with indexed particle rows replaced. .. py:method:: concatenate(evaluations) :classmethod: Concatenate evaluations from multiple particle batches. .. py:method:: select(proposed, accepted) Select proposed values for accepted particles. .. py:method:: to_dict() .. py:method:: from_dict(payload) :classmethod: .. py:method:: encode_for_hdf5() Return the versioned portable HDF5 payload. .. py:method:: save(h5_file_or_group, path = 'target_evaluation') Save this evaluation below ``path`` in an open HDF5 handle. .. py:method:: load(h5_file_or_group, path = 'target_evaluation') :classmethod: Load an evaluation from ``path`` in an open HDF5 handle. .. py:class:: Target Bases: :py:obj:`abc.ABC` Interface for evaluating a target distribution. .. py:property:: evaluation_id :type: str Opaque identity used to validate cached target evaluations. .. py:method:: evaluation_key(context) Return the state of this target relevant to cached evaluations. .. py:method:: accepts_evaluation(evaluation, context) Return whether an evaluation was produced by this target. .. py:method:: bind_evaluation(evaluation, context) Associate an evaluation returned by this target with its identity. .. 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:: prepare_evaluation(particles: sequince.typing.Array, context: sequince.steps.context.StepContext, *, evaluation: TargetEvaluation | None = None, components: collections.abc.Collection[str] | None = None, refresh_components: collections.abc.Collection[str] = (), return_counts: Literal[False] = False) -> TargetEvaluation prepare_evaluation(particles: sequince.typing.Array, context: sequince.steps.context.StepContext, *, evaluation: TargetEvaluation | None = None, components: collections.abc.Collection[str] | None = None, refresh_components: collections.abc.Collection[str] = (), return_counts: Literal[True]) -> tuple[TargetEvaluation, EvaluationCounts] Return a compatible evaluation, optionally with new work counts. ``components`` requests named values, filling any missing cached values. Full requests use ``evaluation_components`` when declared. ``refresh_components`` requests recomputation when a compatible cached evaluation is supplied. .. py:method:: validate_evaluation(evaluation, particles, context) Validate particle alignment and ownership of an evaluation. .. py:method:: evaluate(particles, context, *, components = None, evaluation = None) :abstractmethod: Evaluate or refresh named components of the target. .. py:method:: refresh(particles, evaluation, context, *, components) Refresh named components for an unchanged particle population. .. py:method:: log_prob(particles, context, *, evaluation = None) :abstractmethod: Return the current target log density. .. py:class:: SequentialTarget Bases: :py:obj:`Target` Target that also defines sequential importance-weight increments. .. py:method:: log_increment(particles, context, *, evaluation = None) :abstractmethod: Return the log-weight increment to the next target. .. py:class:: TemperedTarget Bases: :py:obj:`SequentialTarget` Target interpolating geometrically between two endpoint densities. .. py:method:: log_initial(particles, context, *, evaluation = None) :abstractmethod: Return the initial endpoint log density. .. py:method:: log_terminal(particles, context, *, evaluation = None) :abstractmethod: Return the terminal endpoint log density. .. py:method:: log_prob(particles, context, *, evaluation = None) Return the interpolated log density at the current beta. .. py:method:: log_increment(particles, context, *, evaluation = None) Return the terminal-to-initial log-density ratio.