mixle.stats.compute.sampling_api module

A single sample() entry point that draws from any samplable mixle object.

sample(model, size) dispatches on the kind of model so distributions, conjugate posteriors, relations, field posteriors and latent posteriors all read the same way:

mixle.stats.sample(gauss, 100)                 # 100 iid observations
mixle.stats.sample(posterior, 50)              # 50 parameter draws from a conjugate posterior
mixle.stats.sample(assignment, 10, temperature=2.0)   # 10 Gibbs-weighted relation members
mixle.stats.sample(field_post, 100)            # 100 joint field draws (dict per node)
mixle.stats.sample(q_latent, 5)                # 5 latent-variable draws

A shared rng (a numpy.random.RandomState) makes a whole pipeline reproducible: it is threaded into the relation / field / latent draws directly, and for a distribution / conjugate posterior the per-call stream is seeded from it, so one rng drives independent reproducible streams across many sample() calls.

class SampleDispatchRegistration(dispatch_id, handler)

Bases: object

One named extension in the deterministic sample() dispatch order.

Parameters:

• dispatch_id (str)

• handler (Callable[[...], Any])

register_sample_dispatch(dispatch_id, fn=None)

Register a named out-of-core sampler, rejecting duplicate IDs.

Registration order defines dispatch precedence. A handler that does not own model MUST return SAMPLE_UNHANDLED before mutating the model, RNG, or any other observable state.

Parameters:

• dispatch_id (str)

• fn (Callable[[...], Any] | None)

replace_sample_dispatch(dispatch_id, fn)

Explicitly replace an existing named handler without changing its precedence slot.

Parameters:

• dispatch_id (str)

• fn (Callable[[...], Any])

Return type:

Callable[[…], Any]

sample(model, size=None, *, seed=None, rng=None, **kwargs)

Draw sample(s) from any samplable mixle object.

Parameters:

• model (Any) – a distribution, conjugate posterior, Relation, FieldPosterior or LatentPosterior.

• size (int | None) – None returns a single draw in the object’s natural type; a non-negative integer returns a collection (an array for homogeneous leaves, a list / dict-of-arrays for structured draws). Zero returns an empty collection in that natural collection type.

• seed (int | None) – scalar seed for the draw. Mutually exclusive with rng.

• rng (RandomState | None) – a shared RandomState for reproducible, composable streams. Mutually exclusive with seed.

• **kwargs (Any) – forwarded to the underlying sampler – e.g. temperature / k / uniform for a relation, nodes for a field posterior, batched for a distribution.

Returns:

A single draw (size=None) or a collection of size draws.

Raises:

• TypeError – if model is not a recognized samplable object, if size is not an integer or None, or if both seed and rng are supplied (two randomness sources are ambiguous – the same double-supply policy as the constructor keyword aliases).

• ValueError – if size is negative.

Return type:

Any

unregister_sample_dispatch(dispatch_id)

Remove and return an existing named handler.

Parameters:

dispatch_id (str)

Return type:

SampleDispatchRegistration