mixle.enumeration.quantization.seek module

The quantized seek / unrank index over an exact probability-ordered enumeration.

QuantizedEnumerationIndex precomputes how many support values fall in each quantized log-probability bin, so an arbitrary rank can be resolved and unranked without walking the prefix; LazyQuantizedEnumerationIndex builds it on demand and QuantizedCrossIndex indexes the product of two such enumerations. This is the finite/materialized seek index; its exponential-support counterpart – the structural count-budget index – lives in mixle.enumeration.quantization.core.

class QuantizedEnumerationIndex(bins, bin_width_bits, max_bits, truncated)

Bases: object

Bounded, indexable view of an exact probability-ordered enumeration.

Items are grouped into log-probability bins measured in bits:

bits(x) = -log2(p(x)) bin(x) = floor(bits(x) / bin_width_bits)

Only items whose bit cost is at most max_bits are indexed. The returned (value, log_prob) pairs always carry the original exact log probability; the quantized bins are used only for counting and rank lookup.

The generic implementation can build from an exact enumerator stream, so it works for every currently enumerable discrete stats model. Simple distributions may also build directly from scored support items, and distribution-specific dynamic programs can produce the same bin layout without relying on an exact global stream.

Parameters:

• bins (Sequence[tuple[int, list[tuple[Any, float]]]])

• bin_width_bits (float)

• max_bits (float)

• truncated (bool)

static bin_for_log_prob(log_prob, bin_width_bits=1.0)

Return the quantized bit bin for a log probability.

Parameters:

• log_prob (float)

• bin_width_bits (float)

Return type:

int

classmethod from_enumerator(enum, max_bits, bin_width_bits=1.0)

Build an index from an exact non-increasing-probability enumerator.

Parameters:

• enum (Iterator[tuple[Any, float]]) – Iterator yielding (value, log_prob) pairs in exact descending order.

• max_bits (float) – Include only values with -log2(p) <= max_bits.

• bin_width_bits (float) – Width of each quantized probability bin in bits.

Returns:

QuantizedEnumerationIndex over the bounded prefix/domain slice.

Return type:

QuantizedEnumerationIndex

classmethod from_items(items, max_bits, bin_width_bits=1.0, sorted_items=False, truncated=None)

Build an index from known support items and exact log probabilities.

Parameters:

• items (Sequence[tuple[Any, float]]) – Finite collection of (value, log_prob) pairs. Zero-probability items with log_prob == -inf are ignored.

• max_bits (float) – Include only values with -log2(p) <= max_bits.

• bin_width_bits (float) – Width of each quantized probability bin in bits.

• sorted_items (bool) – If True, preserve the input order. Otherwise, stable-sort included items by descending log probability.

• truncated (bool | None) – Optional explicit truncation flag. If omitted, it is True when any finite-probability item was outside the bit bound.

Returns:

QuantizedEnumerationIndex over the bounded finite item set.

Return type:

QuantizedEnumerationIndex

bin_for_index(index)

Return (bin_id, offset_within_bin) for a bounded quantized rank.

Parameters:

index (int)

Return type:

tuple[int, int]

get(index)

Return the indexed (value, exact_log_prob) pair.

Parameters:

index (int)

Return type:

tuple[Any, float]

slice(start, k)

Return up to k indexed pairs starting at start.

Parameters:

• start (int)

• k (int)

Return type:

list[tuple[Any, float]]

iter_from(start=0)

Iterate indexed pairs from start to the end of the bounded index.

Parameters:

start (int)

Return type:

Iterator[tuple[Any, float]]

bin_items(bin_id)

Return all indexed items in a quantized probability bin.

Parameters:

bin_id (int)

Return type:

list[tuple[Any, float]]

summary()

Return a compact description of the bounded index.

Return type:

dict[str, Any]

quantized_index(enum, max_bits, bin_width_bits=1.0)

Convenience wrapper for QuantizedEnumerationIndex.from_enumerator.

Parameters:

• enum (Iterator[tuple[Any, float]])

• max_bits (float)

• bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

class LazyQuantizedEnumerationIndex(counts, bin_width_bits, max_bits, truncated, getter)

Bases: QuantizedEnumerationIndex

Quantized index whose bin counts are precomputed but items are unranked lazily.

This supports compositional distributions where a dynamic program can count how many values fall in each quantized log-density bin without materializing every Cartesian-product value. The getter receives a bin id and offset within that bin and returns the exact (value, log_prob) pair for that quantized rank.

Parameters:

• counts (dict[int, int])

• bin_width_bits (float)

• max_bits (float)

• truncated (bool)

• getter (Callable[[int, int], tuple[Any, float]])

bin_for_index(index)

Return (bin_id, offset_within_bin) for a bounded quantized rank.

Parameters:

index (int)

Return type:

tuple[int, int]

get(index)

Return the indexed (value, exact_log_prob) pair.

Parameters:

index (int)

Return type:

tuple[Any, float]

iter_from(start=0)

Iterate indexed pairs from start to the end of the bounded index.

Parameters:

start (int)

Return type:

Iterator[tuple[Any, float]]

bin_items(bin_id)

Return all indexed items in a quantized probability bin.

Parameters:

bin_id (int)

Return type:

list[tuple[Any, float]]

class QuantizedCrossIndex(items, max_bits, bin_width_bits, truncated=False)

Bases: object

Aligned support rows for multiple distributions under quantized bit bounds.

Each row is (value, log_probs), where log_probs[j] is the exact log-density of value under component j, or -inf when that component assigns zero mass. Rows are included when any component’s bit cost is within its requested bound. The joint bin counts expose the cross-bin alignment that mixtures need and marginal bin counts cannot provide.

Parameters:

• items (Sequence[tuple[Any, Sequence[float]]])

• max_bits (Sequence[float])

• bin_width_bits (float)

• truncated (bool)

static bits_for_log_prob(log_prob)

Return -log2(p), using inf for zero probability.

Parameters:

log_prob (float)

Return type:

float

classmethod from_items(items, max_bits, bin_width_bits=1.0, truncated=False)

Build a cross index from exact aligned support rows.

Parameters:

• items (Sequence[tuple[Any, Sequence[float]]])

• max_bits (Sequence[float])

• bin_width_bits (float)

• truncated (bool)

Return type:

QuantizedCrossIndex

iter_items()

Iterate aligned support rows.

Return type:

Iterator[tuple[Any, tuple[float, …]]]

summary()

Return a compact description of the cross index.

Return type:

dict[str, Any]