Module iface 

The main export of this module is the dyn compatible Quantizer trait, which provides a common interface for interacting with bit-width specific SphericalQuantizers, compressing vectors, and computing distances between compressed vectors.

This is offered as a convenience interface for interacting with the myriad of generics associated with the SphericalQuantizer. Better performance can be achieved by using the generic types directly if desired.

The Quantizer uses the Opaque and OpaqueMut types for its compressed data representations. These are thin wrappers around raw byte slices.

Distance computation is performed using DistanceComputer and QueryComputer

Concrete implementations of Quantizer are available via the generic struct Impl.

Compatibility Table

Multiple QueryLayouts are supported when constructing a QueryComputer, but not all layouts are supported for each back end. This table lists the valid instantiations of Impl (parameterized by data vector bit-width) and their supported query layouts.

Bits	Same As Data	Full Precision	Four-Bit Transposed	Scalar Quantized
1	Yes	Yes	Yes	No
2	Yes	Yes	No	Yes
4	Yes	Yes	No	Yes
8	Yes	Yes	No	Yes

Example

use diskann_quantization::{
    alloc::{Poly, ScopedAllocator, AlignedAllocator, GlobalAllocator},
    algorithms::TransformKind,
    spherical::{iface, SupportedMetric, SphericalQuantizer, PreScale},
    num::PowerOfTwo,
};
use diskann_utils::views::Matrix;

// For illustration purposes, the dataset consists of just a single vector.
let mut data = Matrix::new(1.0, 1, 4);
let quantizer = SphericalQuantizer::train(
    data.as_view(),
    TransformKind::Null,
    SupportedMetric::SquaredL2,
    PreScale::None,
    &mut rand::rng(),
    GlobalAllocator
).unwrap();

let quantizer: Box<dyn iface::Quantizer> = Box::new(
    iface::Impl::<1>::new(quantizer).unwrap()
);

let alloc = AlignedAllocator::new(PowerOfTwo::new(1).unwrap());
let mut buf = Poly::broadcast(u8::default(), quantizer.bytes(), alloc).unwrap();

quantizer.compress(
    data.row(0),
    iface::OpaqueMut::new(&mut buf),
    ScopedAllocator::new(&alloc),
).unwrap();

assert!(quantizer.is_supported(iface::QueryLayout::FullPrecision));
assert!(!quantizer.is_supported(iface::QueryLayout::ScalarQuantized));

Structs

DistanceComputer

An opaque DistanceFunction for the Quantizer trait object.

Impl

Implementation for Quantizer specializing on the number of bits used for data compression.

NotCanonical

Opaque

A type-erased slice wrapper used to hide the implementation of spherically quantized vectors. This allows multiple bit-width implementations to share the same type.

OpaqueMut

A type-erased slice wrapper used to hide the implementation of spherically quantized vectors. This allows multiple bit-width implementations to share the same type.

QueryBufferDescription

A description of the buffer size (in bytes) and alignment required for a compressed query.

QueryComputer

An opaque PreprocessedDistanceFunction for the Quantizer trait object.

UnsupportedQueryLayout

Enums

CompressionError

Errors that can occur during data compression

DeserializationErrorflatbuffers

DistanceComputerError

DistanceError

Errors that can occur while perfoming distance cacluations on opaque vectors.

QueryCompressionError

QueryComputerError

QueryDistanceError

Errors that can occur while perfoming distance cacluations on opaque vectors.

QueryLayout

The layout to use for the query in DistanceComputer and QueryComputer.

Traits

Constructible

Pre-dispatch distance functions between compressed data vectors from quantizer specialized for the current run-time mciro architecture.

DynDistanceComputer

DynQueryComputer

Quantizer

A dyn-compatible trait providing a common interface for a bit-width specific SphericalQuantizer.

Functions

try_deserializeflatbuffers

Attempt to deserialize a spherical::Quantizer flatbuffer into one of the concrete implementations of Quantizer.