mixle.stats.compute.kernel module¶

Backend-neutral evaluation kernel contracts.

The generic kernel is a thin adapter over the existing seq_* protocol. It is the guaranteed fallback for engine-aware orchestration; specialized factories can override code shape for performance without changing estimators.

exception EngineNotSupportedError[source]

Bases: ValueError

Raised when no kernel can safely evaluate a distribution on an engine.

class Kernel[source]

Bases: ABC

Evaluation kernel for a fitted distribution.

abstractmethod score(enc)[source]

Return per-row log densities for an encoded observation batch.

Parameters:

enc (Any)

Return type:

Any

component_scores(enc)[source]

Return per-row, per-component log densities where meaningful.

Parameters:

enc (Any)

Return type:

Any

abstractmethod accumulate(enc, weights)[source]

Return sufficient statistics in the legacy estimator format.

Parameters:
Return type:

Any

abstractmethod refresh(dist)[source]

Refresh kernel parameters after an EM M-step without rebuilding structure.

Parameters:

dist (SequenceEncodableProbabilityDistribution)

Return type:

None

class KernelFactory[source]

Bases: ABC

Factory that builds a Kernel for a distribution and engine.

abstractmethod build(dist, engine, estimator=None)[source]

Return a kernel for dist on engine.

estimator is optional for pure scoring and required for kernels that need to emit sufficient statistics for an M-step.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • engine (ComputeEngine)

  • estimator (ParameterEstimator | None)

Return type:

Kernel

class GenericKernel(dist, engine=NUMPY_ENGINE, estimator=None)[source]

Bases: Kernel

Fallback kernel over distribution-owned backend hooks or existing seq_* methods.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • engine (ComputeEngine)

  • estimator (ParameterEstimator | None)

score(enc)[source]

Return per-row log densities using backend hooks when available.

Parameters:

enc (Any)

Return type:

Any

component_scores(enc)[source]

Return per-row component log densities for mixture-like models.

Parameters:

enc (Any)

Return type:

Any

accumulate(enc, weights)[source]

Accumulate weighted sufficient statistics in estimator-owned format.

Parameters:
Return type:

Any

refresh(dist)[source]

Replace the fitted distribution while preserving kernel structure.

Parameters:

dist (SequenceEncodableProbabilityDistribution)

Return type:

None

class GenericKernelFactory[source]

Bases: KernelFactory

Guaranteed fallback factory for distributions that support the engine.

build(dist, engine, estimator=None)[source]

Build a generic kernel or fail fast when the engine is unsupported.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • engine (ComputeEngine)

  • estimator (ParameterEstimator | None)

Return type:

GenericKernel

class NumbaKernel(dist, engine=NUMPY_ENGINE, estimator=None)[source]

Bases: Kernel

Kernel adapter over the existing fused-numba CompiledMixture path.

This kernel intentionally uses the columnar encoding returned by encode(data) rather than the legacy dist_to_encoder().seq_encode payload. That keeps the high-performance path explicit while giving it the same score/accumulate/refresh surface as other engines.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • engine (ComputeEngine)

  • estimator (ParameterEstimator | None)

encode(data)[source]

Encode raw observations into the fused columnar kernel format.

Parameters:

data (Any)

Return type:

Any

score(enc)[source]

Return per-row log densities from the fused numba mixture kernel.

Parameters:

enc (Any)

Return type:

ndarray

component_scores(enc)[source]

Return per-row, per-component log densities from the fused kernel.

Parameters:

enc (Any)

Return type:

ndarray

accumulate(enc, weights)[source]

Use fused posteriors plus row weights to produce legacy statistics.

Parameters:
Return type:

Any

refresh(dist)[source]

Refresh parameters after an M-step without rebuilding the compiled object.

Parameters:

dist (SequenceEncodableProbabilityDistribution)

Return type:

None

class GeneratedNumbaKernel(dist, engine=NUMPY_ENGINE, estimator=None)[source]

Bases: Kernel

Generated numba kernel from declaration exponential-family metadata.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • engine (ComputeEngine)

  • estimator (ParameterEstimator | None)

encode(data)[source]

Encode raw observations with the distribution’s ordinary encoder.

Parameters:

data (Any)

Return type:

Any

score(enc)[source]

Return per-row log densities from declaration-generated numba code.

Parameters:

enc (Any)

Return type:

ndarray

component_scores(enc)[source]

Return generated component scores for homogeneous generated mixtures.

Parameters:

enc (Any)

Return type:

ndarray

accumulate(enc, weights)[source]

Accumulate generated sufficient statistics for leaves or mixtures.

Parameters:
Return type:

Any

posteriors(enc)[source]

Return normalized mixture posterior weights for generated mixtures.

Parameters:

enc (Any)

Return type:

ndarray

refresh(dist)[source]

Refresh the distribution and regenerated component metadata.

Parameters:

dist (SequenceEncodableProbabilityDistribution)

Return type:

None

class NumbaKernelFactory[source]

Bases: KernelFactory

Factory for generated declaration numba kernels with legacy fused fallback.

build(dist, engine, estimator=None)[source]

Prefer generated numba kernels, then fused kernels, then stacked fallback.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • engine (ComputeEngine)

  • estimator (ParameterEstimator | None)

Return type:

Kernel

class GeneratedNumbaKernelFactory(fallback=None)[source]

Bases: KernelFactory

Default-safe factory that prefers declaration-generated numba kernels.

Unlike NumbaKernelFactory, this never selects the fused CompiledMixture adapter (whose columnar encoding is incompatible with the legacy seq_encode payloads that the engine estimation path feeds kernels) and never raises: when a generated numba scorer is unavailable, or the engine is not numpy, it defers to a guaranteed fallback (the generic kernel). That makes it safe to register as a default on the kernel dispatch path while still accelerating mixtures of declared exponential-family leaves on the numpy engine.

Parameters:

fallback (KernelFactory | None)

build(dist, engine, estimator=None)[source]

Build a generated numba kernel on numpy when available, else fall back.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • engine (ComputeEngine)

  • estimator (ParameterEstimator | None)

Return type:

Kernel

register_kernel_factory(dist_type, factory)[source]

Register a specialized kernel factory for a distribution class.

Parameters:

  • dist_type (type[Any])

  • factory (KernelFactory)

Return type:

None

kernel_for(dist, engine=None, estimator=None)[source]

Build the best registered kernel for dist and engine.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • engine (ComputeEngine | None)

  • estimator (ParameterEstimator | None)

Return type:

Kernel