veloxquant_mlx.handlers.normalization module

Handler stage that normalizes vectors to unit L2 norm and restores scale on decode.

Typically the first stage in an encode chain: it factors each input vector into a stored scalar norm (ctx.norm) and a unit-norm direction, so that downstream stages (rotation, polar transform, scalar quantization) always operate on scale-normalized data. On decode it multiplies the reconstructed direction back by the stored norm.

class veloxquant_mlx.handlers.normalization.NormalizationHandler(eps=1e-08)

Bases: QuantizationHandler

Normalise input vectors to unit L2 norm (encode) or restore scale (decode).

On encode:

norm = ‖x‖₂ stored in ctx.norm x_current = x / norm

On decode:

x_current = x_current * norm (restores original scale)

Parameters:

eps (float) – Small value added to norm to avoid division by zero.

handle(ctx)

Process normalisation in the context’s current mode.

Parameters:

ctx (QuantizationContext) – Quantization context.

Return type:

QuantizationContext

Returns:

Updated context (norm and x_current modified).

property handler_name: str

Registry name for this handler (‘normalization’).