sequince.target

sequince.target#

Attributes#

logger

TargetComponentFn

Classes#

EvaluationCounts

Backend-compatible counters for probabilistic model evaluations.

TargetEvaluation

Named, particle-aligned values evaluated by a target.

Target

Interface for evaluating a target distribution.

SequentialTarget

Target that also defines sequential importance-weight increments.

TemperedTarget

Target interpolating geometrically between two endpoint densities.

Module Contents#

sequince.target.logger#
sequince.target.TargetComponentFn#
class sequince.target.EvaluationCounts[source]#

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.

log_target_evaluations: Any = 0#
log_likelihood_evaluations: Any = 0#
log_proposal_evaluations: Any = 0#
log_increment_evaluations: Any = 0#
classmethod zeros(*, xp=None)[source]#

Return zero counts, optionally as scalars from an array namespace.

Parameters:

xp (Any | None)

Return type:

EvaluationCounts

class sequince.target.TargetEvaluation[source]#

Named, particle-aligned values evaluated by a target.

components: collections.abc.Mapping[str, sequince.typing.Array]#
target_id: str | None = None#
evaluation_key: collections.abc.Hashable | None = None#
property n_particles: int#

Number of particle-aligned entries in the evaluation.

Return type:

int

validate_for(particles)[source]#

Validate that this evaluation has one entry per supplied particle.

Parameters:

particles (sequince.typing.Array)

Return type:

None

with_target(target_id, evaluation_key)[source]#

Return this evaluation associated with a target state.

Parameters:
Return type:

TargetEvaluation

copy()[source]#

Return a detached copy preserving array backends.

Return type:

TargetEvaluation

take(indices)[source]#

Select particle evaluations using ancestor indices.

Parameters:

indices (sequince.typing.Array)

Return type:

TargetEvaluation

replace(indices, replacement)[source]#

Return an evaluation with indexed particle rows replaced.

Parameters:
Return type:

TargetEvaluation

classmethod concatenate(evaluations)[source]#

Concatenate evaluations from multiple particle batches.

Parameters:

evaluations (collections.abc.Collection[TargetEvaluation])

Return type:

TargetEvaluation

select(proposed, accepted)[source]#

Select proposed values for accepted particles.

Parameters:
Return type:

TargetEvaluation

to_dict()[source]#
Return type:

dict[str, Any]

classmethod from_dict(payload)[source]#
Parameters:

payload (collections.abc.Mapping[str, Any])

Return type:

TargetEvaluation

encode_for_hdf5()[source]#

Return the versioned portable HDF5 payload.

Return type:

dict[str, Any]

save(h5_file_or_group, path='target_evaluation')[source]#

Save this evaluation below path in an open HDF5 handle.

Parameters:

  • h5_file_or_group (Any)

  • path (str)

Return type:

None

classmethod load(h5_file_or_group, path='target_evaluation')[source]#

Load an evaluation from path in an open HDF5 handle.

Parameters:

  • h5_file_or_group (Any)

  • path (str)

Return type:

Self

class sequince.target.Target[source]#

Bases: abc.ABC

Interface for evaluating a target distribution.

property evaluation_id: str#

Opaque identity used to validate cached target evaluations.

Return type:

str

evaluation_key(context)[source]#

Return the state of this target relevant to cached evaluations.

Parameters:

context (sequince.steps.context.StepContext)

Return type:

collections.abc.Hashable | None

accepts_evaluation(evaluation, context)[source]#

Return whether an evaluation was produced by this target.

Parameters:
Return type:

bool

bind_evaluation(evaluation, context)[source]#

Associate an evaluation returned by this target with its identity.

Parameters:
Return type:

TargetEvaluation

evaluation_components(context)[source]#

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.

Parameters:

context (sequince.steps.context.StepContext)

Return type:

collections.abc.Collection[str] | None

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[source]#
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.

validate_evaluation(evaluation, particles, context)[source]#

Validate particle alignment and ownership of an evaluation.

Parameters:
Return type:

None

abstractmethod evaluate(particles, context, *, components=None, evaluation=None)[source]#

Evaluate or refresh named components of the target.

Parameters:
Return type:

TargetEvaluation

refresh(particles, evaluation, context, *, components)[source]#

Refresh named components for an unchanged particle population.

Parameters:
Return type:

TargetEvaluation

abstractmethod log_prob(particles, context, *, evaluation=None)[source]#

Return the current target log density.

Parameters:
Return type:

sequince.typing.Array | float

class sequince.target.SequentialTarget[source]#

Bases: Target

Target that also defines sequential importance-weight increments.

abstractmethod log_increment(particles, context, *, evaluation=None)[source]#

Return the log-weight increment to the next target.

Parameters:
Return type:

sequince.typing.Array | float

class sequince.target.TemperedTarget[source]#

Bases: SequentialTarget

Target interpolating geometrically between two endpoint densities.

abstractmethod log_initial(particles, context, *, evaluation=None)[source]#

Return the initial endpoint log density.

Parameters:
Return type:

sequince.typing.Array | float

abstractmethod log_terminal(particles, context, *, evaluation=None)[source]#

Return the terminal endpoint log density.

Parameters:
Return type:

sequince.typing.Array | float

log_prob(particles, context, *, evaluation=None)[source]#

Return the interpolated log density at the current beta.

Parameters:
Return type:

sequince.typing.Array | float

log_increment(particles, context, *, evaluation=None)[source]#

Return the terminal-to-initial log-density ratio.

Parameters:
Return type:

sequince.typing.Array | float