Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompressionRatio ¶
CompressionRatio returns the storage ratio: quantized size / original float64 size.
func CosineSimilarity ¶
func CosineSimilarity(a, b *QuantizedVector) (float64, error)
CosineSimilarity estimates the cosine similarity between two quantized vectors.
func Dequantize ¶
func Dequantize(qv *QuantizedVector) ([]float64, error)
Dequantize reconstructs an approximate vector from its quantized representation.
func InnerProduct ¶
func InnerProduct(a, b *QuantizedVector) (float64, error)
InnerProduct estimates the inner product <a, b> from two quantized vectors using the MSE estimator. Both vectors must have the same dimension and seed.
Types ¶
type Codebook ¶
type Codebook struct {
Bits int
Levels int // 2^Bits
Thresholds []float64 // len = Levels-1, decision boundaries
Centers []float64 // len = Levels, reconstruction values
}
Codebook holds precomputed Lloyd-Max quantization levels and thresholds for a given bit width, optimized for N(0,1) distributed inputs. These values are derived from the TurboQuant paper (arXiv 2504.19874), which shows that random rotation induces approximately normal coordinates.
func GetCodebook ¶
GetCodebook returns the precomputed Lloyd-Max codebook for a given bit width. Supported bit widths are 1, 2, 3, and 4.
func (*Codebook) Dequantize ¶
Dequantize maps a codebook index back to the reconstruction center value.
func (*Codebook) MSEDistortion ¶
MSEDistortion returns the theoretical mean squared error for this codebook when applied to N(0,1) inputs, following the TurboQuant bound: D_mse <= (sqrt(3)*pi/2) * (1/4^b)
type Config ¶
type Config struct {
Bits int // Bit width per coordinate: 1, 2, 3, or 4. Default: 2.
Seed int64 // Random rotation seed. Default: 42.
}
Config controls quantization behavior.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns sensible defaults (2-bit quantization, seed 42).
type QuantizedVector ¶
type QuantizedVector struct {
Dim int // Original dimension
Bits int // Bit width used
Seed int64 // Rotation seed (needed for dequantization)
Codes []byte // Packed quantization codes
Norm float64 // Original L2 norm (stored for cosine similarity)
}
QuantizedVector is the compact representation of a quantized vector. At 2 bits per dimension, a 384-dim vector compresses from 3072 bytes (float64) to 96 bytes — a 32x reduction.
type RotationMatrix ¶
type RotationMatrix struct {
// contains filtered or unexported fields
}
RotationMatrix represents a random orthogonal rotation implemented via chained Householder reflections. This avoids materializing the full d×d matrix, keeping memory at O(k*d) where k is the number of reflections.
The rotation is data-oblivious (depends only on the seed), which is a key property from TurboQuant: the same rotation works for any input distribution, and after rotation each coordinate is approximately N(0, 1/d) for unit-norm vectors.
func NewRotation ¶
func NewRotation(dim int, seed int64) *RotationMatrix
NewRotation creates a random orthogonal rotation for the given dimension using the specified seed. The rotation is deterministic for the same (dim, seed) pair.
func (*RotationMatrix) Apply ¶
func (r *RotationMatrix) Apply(x []float64)
Apply rotates vector x in-place using the chain of Householder reflections. Each reflection is: x ← x - 2*(v·x)*v
func (*RotationMatrix) ApplyInverse ¶
func (r *RotationMatrix) ApplyInverse(x []float64)
ApplyInverse rotates vector x in-place by the inverse rotation (R^T). Since each Householder reflection is its own inverse, we apply them in reverse order.
Source Files