mixle.stats.compute.declarations module

Declarative metadata for distribution parameters and sufficient statistics.

class ParameterSpec(name, constraint='real', differentiable=True)

Bases: object

A fitted distribution parameter used by scoring.

Constraints are interpreted by generic generated/scoring utilities. In addition to scalar constraints such as positive and vector/matrix constraints such as simplex_vector, row_simplex_matrix, and column_simplex_matrix, greater_than:<parameter> marks a coupled ordered bound.

Parameters:

• name (str)

• constraint (str)

• differentiable (bool)

name: str

constraint: str = 'real'

differentiable: bool = True

class StatisticSpec(name, kind='moment', additive=True, scales=True)

Bases: object

A sufficient-statistic entry produced by accumulation.

Parameters:

• name (str)

• kind (str)

• additive (bool)

• scales (bool)

name: str

kind: str = 'moment'

additive: bool = True

scales: bool = True

class ExponentialFamilySpec(sufficient_statistics, natural_parameters, log_partition, base_measure=None, sufficient_statistics_from_params=None, base_measure_from_params=None, legacy_sufficient_statistics=None, fixed_base=True, runtime_scoring=True)

Bases: object

Conditional exponential-family pieces for generated scalar scoring.

Parameters:

• sufficient_statistics (Callable[[Any, Any], tuple[Any, ...]])

• natural_parameters (Callable[[dict[str, Any], Any], tuple[Any, ...]])

• log_partition (Callable[[dict[str, Any], Any], Any])

• base_measure (Callable[[Any, Any], Any] | None)

• sufficient_statistics_from_params (Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None)

• base_measure_from_params (Callable[[Any, dict[str, Any], Any], Any] | None)

• legacy_sufficient_statistics (Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None)

• fixed_base (bool)

• runtime_scoring (bool)

sufficient_statistics: Callable[[Any, Any], tuple[Any, ...]]

natural_parameters: Callable[[dict[str, Any], Any], tuple[Any, ...]]

log_partition: Callable[[dict[str, Any], Any], Any]

base_measure: Callable[[Any, Any], Any] | None = None

sufficient_statistics_from_params: Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None = None

base_measure_from_params: Callable[[Any, dict[str, Any], Any], Any] | None = None

legacy_sufficient_statistics: Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None = None

fixed_base: bool = True

runtime_scoring: bool = True

Whether the generated exp-family form may drive runtime scoring (scalar + stacked + numba).

Set False when the canonical <eta, T(x)> dot form is numerically unsafe as a runtime scorer even though the family is a valid exponential family. The motivating case is the categorical: eta = log(p) has -inf entries for zero-probability categories, so the generic dot product hits 0 * -inf = NaN for observations of other categories (its own seq_log_density avoids this by indexing). With runtime_scoring=False the family keeps its backend_* scoring path while to_exponential_family still exposes the canonical map (valid where p > 0).

class DistributionDeclaration(name, distribution_type, parameters, statistics, support, children=(), child_roles=(), differentiable=True, exponential_family=None, legacy_sufficient_statistics=None)

Bases: object

Metadata needed by generated kernels and future autograd paths.

Parameters:

• name (str)

• distribution_type (type[Any])

• parameters (tuple[ParameterSpec, ...])

• statistics (tuple[StatisticSpec, ...])

• support (str)

• children (tuple[DistributionDeclaration, ...])

• child_roles (tuple[str, ...])

• differentiable (bool)

• exponential_family (ExponentialFamilySpec | None)

• legacy_sufficient_statistics (Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None)

name: str

distribution_type: type[Any]

parameters: tuple[ParameterSpec, ...]

statistics: tuple[StatisticSpec, ...]

support: str

children: tuple[DistributionDeclaration, ...] = ()

child_roles: tuple[str, ...] = ()

differentiable: bool = True

exponential_family: ExponentialFamilySpec | None = None

legacy_sufficient_statistics: Callable[[Any, dict[str, Any], Any], tuple[Any, ...]] | None = None

parameter_values(dist)

Extract declared parameter values from a distribution instance.

Parameters:

dist (Any)

Return type:

dict[str, Any]

statistic_values(suff_stat)

Map a legacy accumulator value into declared statistic names.

Parameters:

suff_stat (Any)

Return type:

dict[str, Any]

property parameter_names: tuple[str, ...]

Return declared parameter names in storage order.

property statistic_names: tuple[str, ...]

Return declared sufficient-statistic names in accumulator order.

property has_exponential_family: bool

Return whether generated exponential-family scoring is available.

register_declaration(declaration)

Register a declaration for a distribution class.

Parameters:

declaration (DistributionDeclaration)

Return type:

None

declaration_for(x)

Return a declaration for a distribution instance or class, if present.

Parameters:

x (Any)

Return type:

DistributionDeclaration | None

declared_distribution_types()

Return classes that currently have declarations.

Return type:

Iterable[type[Any]]

declaration_issues(x)

Return structural issues in a distribution declaration.

This is intentionally schema-level validation: it checks names, constraints, child roles, and callable exponential-family pieces without importing or special-casing concrete distribution implementations.

Parameters:

x (Any)

Return type:

tuple[str, …]

validate_declaration(x)

Return a declaration or raise ValueError with schema issues.

Parameters:

x (Any)

Return type:

DistributionDeclaration

statistic_layout_issues(x, suff_stat)

Return issues mapping a legacy sufficient-statistic payload to a declaration.

This validates the top-level statistic_values(...) arity and, when a declaration exposes child roles, recursively validates child statistic payloads for tuple/list/map-shaped entries. It stays schema-driven and does not import concrete distribution implementations.

Parameters:

• x (Any)

• suff_stat (Any)

Return type:

tuple[str, …]

validate_statistic_layout(x, suff_stat)

Return a declaration or raise ValueError with statistic-layout issues.

Parameters:

• x (Any)

• suff_stat (Any)

Return type:

DistributionDeclaration

generated_stacked_available(dist_type)

Return true when declarations can generate stacked leaf scoring.

Parameters:

dist_type (type[Any])

Return type:

bool

generated_stacked_preferred(dist_type)

Return true when a family explicitly opts into declaration-generated scoring.

Parameters:

dist_type (type[Any])

Return type:

bool

generated_stacked_strategy(dist_type)

Describe the declaration-generated stacked scoring route for a family.

Parameters:

dist_type (type[Any])

Return type:

str

generated_log_density_diagnostics(x, encoded_symbols=None)

Trace a generated scalar log-density formula with the symbolic engine.

The returned dictionary contains the symbolic expression string, referenced data/parameter symbols, operation counts, and expression depth. This is an author-facing inspection tool for declaration-generated kernels; it does not select or execute a runtime backend.

Parameters:

• x (Any)

• encoded_symbols (Sequence[str] | None)

Return type:

dict[str, Any]

generated_stacked_params(dists, engine)

Stack declared distribution parameters for generated homogeneous-mixture scoring.

The generated path is intentionally conservative: it supports scalar, vector, or matrix per-component parameters that can be broadcast over per-row encoded fields. Non-differentiable support metadata such as integer bounds must still be shared across components unless a family keeps an explicit backend_stacked_* route.

Parameters:

• dists (Sequence[Any])

• engine (Any)

Return type:

dict[str, Any]

generated_stacked_log_density(enc, params, engine)

Return an (n, k) log-density matrix from declaration-stacked params.

Parameters:

• enc (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

generated_log_density(dist, enc, engine)

Return per-row log densities from declaration-owned scoring metadata.

This is the single-distribution counterpart of generated_stacked_log_density. It gives generic kernels an engine-aware fallback before they drop to legacy NumPy seq_log_density methods, and it stays fully metadata-driven: no caller imports or switches on concrete distribution implementations.

Parameters:

• dist (Any)

• enc (Any)

• engine (Any)

Return type:

Any

generated_stacked_sufficient_statistics_available(x)

Return true when a declaration can generate resident stacked stats.

Parameters:

x (Any)

Return type:

bool

generated_sufficient_statistics_available(x)

Return true when a declaration can generate single-distribution stats.

Parameters:

x (Any)

Return type:

bool

generated_sufficient_statistics(dist, enc, weights, engine)

Return legacy sufficient statistics from declaration-owned row stats.

This is the single-distribution analogue of generated_stacked_sufficient_statistics. It performs row-wise sufficient-statistic algebra on the active engine, then converts only the small legacy payload back across the boundary for the existing estimator M-step.

Parameters:

• dist (Any)

• enc (Any)

• weights (Any)

• engine (Any)

Return type:

tuple[Any, …]

generated_numba_log_density_available(x)

Return true when declarations can emit a generated numba leaf scorer.

Exponential-family leaves use the stacked exp-family loop; other leaves with a backend_log_density_from_params hook whose per-row formula lowers cleanly to a numba scalar loop (single encoded array, supported ops, scalar parameters) use the generic symbolic-to-numba compiler in _build_generic_numba_kernel().

Parameters:

x (Any)

Return type:

bool

generated_numba_stacked_available(x)

Return true when declarations can emit a generated stacked numba scorer.

Parameters:

x (Any)

Return type:

bool

generated_numba_log_density(dist, enc)

Return per-row log densities from a declaration-generated numba loop.

The generated loop evaluates the exponential-family form base(x) + T(x) dot eta(theta) - A(theta). Distribution declarations still own the statistical metadata; this helper only lowers the row fold to a nopython scalar loop.

Parameters:

• dist (Any)

• enc (Any)

Return type:

ndarray

generated_numba_stacked_log_density(enc, params)

Return an (n, k) score matrix from a declaration-generated numba loop.

Parameters:

• enc (Any)

• params (dict[str, Any])

Return type:

ndarray

generated_stacked_sufficient_statistics(enc, weights, params, engine)

Return component-stacked legacy sufficient statistics from declarations.

Parameters:

• enc (Any)

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]