Struct SphericalQuantizer 

pub struct SphericalQuantizer<A = GlobalAllocator>
where
    A: Allocator,
{ /* private fields */ }

Implementations

impl<A> SphericalQuantizer<A>

where A: Allocator,

pub fn input_dim(&self) -> usize

Return the number dimensions this quantizer has been trained for.

pub fn output_dim(&self) -> usize

Return the dimension of the post-transformed vector.

Output storage vectors should use this dimension instead of self.dim() because in general, the output dim may be different from the input dimension.

pub fn shift(&self) -> &[f32]

Return the per-dimension shift vector.

This vector is meant to accomplish two goals:

1. Centers the data around the training dataset mean.
2. Offsets each dimension into a range that can be encoded in unsigned values.

pub fn mean_norm(&self) -> Positive<f32>

Return the approximate mean norm of the training data.

pub fn pre_scale(&self) -> Positive<f32>

Return the pre-scaling parameter for data. This value is multiplied to every compressed vector to adjust its dynamic range.

A value of 1.0 means that no scaling is occurring.

pub fn allocator(&self) -> &A

Return a reference to the allocator used by this data structure.

pub fn generate( centroid: Poly<[f32], A>, mean_norm: f32, transform: TransformKind, metric: SupportedMetric, pre_scale: Option<f32>, rng: &mut dyn RngCore, allocator: A, ) -> Result<Self, TrainError>

A lower-level constructor that accepts a centroid, mean norm, and pre-scale directly.

pub fn metric(&self) -> SupportedMetric

Return the metric used by this quantizer.

pub fn train<T, R>( data: MatrixView<'_, T>, transform: TransformKind, metric: SupportedMetric, pre_scale: PreScale, rng: &mut R, allocator: A, ) -> Result<Self, TrainError>

where T: Copy + Into<f64> + Into<f32>, R: Rng,

Construct a quantizer for vectors in the distribution of data.

The type of distance-preserving transform to use is selected by the TransformKind.

Vectors compressed with this quantizer will be metric specific and optimized for distance computations rather than reconstruction. This means that vectors compressed targeting the inner-product distance will not return meaningful results if used for L2 distance computations.

Additionally, vectors compressed when using the SupportedMetric::Cosine distance will be implicitly normalized before being compressed to enable better compression.

If argument pre_scale is given, then all vectors compressed by this quantizer will first be scaled by this value. Note that if given, pre_scale must be positive.

pub fn rescale(&self, v: &mut [f32])

Rescale the argument v to be in the rough dynamic range of the training dataset.

Trait Implementations

impl<A> AsFunctor<CompensatedCosine> for SphericalQuantizer<A>

where A: Allocator,

fn as_functor(&self) -> CompensatedCosine

impl<A> AsFunctor<CompensatedIP> for SphericalQuantizer<A>

where A: Allocator,

fn as_functor(&self) -> CompensatedIP

impl<A> AsFunctor<CompensatedSquaredL2> for SphericalQuantizer<A>

where A: Allocator,

fn as_functor(&self) -> CompensatedSquaredL2

impl<A> CompressIntoWith<&[f32], Slice<&mut [f32], Mut<'_, FullQueryMeta>>, ScopedAllocator<'_>> for SphericalQuantizer<A>

where A: Allocator,

fn compress_into_with( &self, from: &[f32], into: FullQueryMut<'_>, allocator: ScopedAllocator<'_>, ) -> Result<(), Self::Error>

Compress the input vector from into the bitslice into.

Error

Returns an error if

• The input contains NaN.
• from.len() != self.dim(): Vector to be compressed must have the same dimensionality as the quantizer.
• into.len() != self.output_dim(): Compressed vector must have the same dimensionality as the output of the distance-preserving transform. Importantely, this may be different than self.dim() and should be retrieved from self.output_dim().

type Error = CompressionError

Errors that may occur during compression.

impl<const NBITS: usize, A> CompressIntoWith<&[f32], VectorBase<NBITS, Unsigned, MutSlicePtr<'_, u8>, Mut<'_, DataMeta>>, ScopedAllocator<'_>> for SphericalQuantizer<A>

where A: Allocator, Unsigned: Representation<NBITS>, for<'a> DataMut<'a, NBITS>: FinishCompressing,

fn compress_into_with( &self, from: &[f32], into: DataMut<'_, NBITS>, allocator: ScopedAllocator<'_>, ) -> Result<(), Self::Error>

Compress the input vector from into the bitslice into.

Error

Returns an error if

• The input contains NaN.
• from.len() != self.dim(): Vector to be compressed must have the same dimensionality as the quantizer.
• into.len() != self.output_dim(): Compressed vector must have the same dimensionality as the output of the distance-preserving transform. Importantely, this may be different than self.dim() and should be retrieved from self.output_dim().

type Error = CompressionError

Errors that may occur during compression.

impl<const NBITS: usize, Perm, A> CompressIntoWith<&[f32], VectorBase<NBITS, Unsigned, MutSlicePtr<'_, u8>, Mut<'_, QueryMeta>, Perm>, ScopedAllocator<'_>> for SphericalQuantizer<A>

where Unsigned: Representation<NBITS>, Perm: PermutationStrategy<NBITS>, A: Allocator,

fn compress_into_with( &self, from: &[f32], into: QueryMut<'_, NBITS, Perm>, allocator: ScopedAllocator<'_>, ) -> Result<(), Self::Error>

Compress the input vector from into the bitslice into.

Error

Returns an error if

• The input contains NaN.
• from.len() != self.dim(): Vector to be compressed must have the same dimensionality as the quantizer.
• into.len() != self.output_dim(): Compressed vector must have the same dimensionality as the output of the distance-preserving transform. Importantely, this may be different than self.dim() and should be retrieved from self.output_dim().

type Error = CompressionError

Errors that may occur during compression.

impl<A> Debug for SphericalQuantizer<A>

where A: Allocator + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.