veloxquant_mlx.codebooks.base module

Factory for building ScalarCodebook instances from a distribution name.

Central entry point for codebook construction: CodebookFactory.create maps a distribution string ("gaussian", "beta", "polar_level", "uniform") to the matching registered CodebookStrategy (see strategies), fits centroids for the requested bit-width and dimension, and wraps them in a ScalarCodebook. All codebook instantiation in the codebase should go through this factory rather than constructing strategies directly.

class veloxquant_mlx.codebooks.base.CodebookFactory[source]

Bases: object

Factory for creating ScalarCodebook instances via registered strategies.

All instantiation of codebooks should go through this factory.

Example:

cb = CodebookFactory.create("gaussian", b=2, d=128)
static create(distribution, b, d, polar_level=1)[source]

Create a ScalarCodebook for the given distribution and bit-width.

Parameters:

  • distribution (Literal['gaussian', 'beta', 'polar_level', 'uniform']) – Centroid distribution type. - "gaussian": N(0, 1/d) — high-d TurboQuant. - "beta": exact Beta distribution — low-d TurboQuant. - "polar_level": polar angle distribution (requires polar_level). - "uniform": uniformly spaced centroids.

  • b (int) – Bit-width (1 <= b <= 8).

  • d (int) – Vector dimension.

  • polar_level (int) – Polar recursion level (only used when distribution=”polar_level”).

Return type:

ScalarCodebook

Returns:

Configured ScalarCodebook instance, memoized by (distribution, b, d, polar_level) (VeloxQuant-MLX#508) — centroid construction is a pure, deterministic function of these args, and ScalarCodebook is read-only after construction, so it’s safe to share across callers.

Raises:

QuantizerConfigError – If parameters are invalid.