Trait Quantizer 

pub trait Quantizer<A = GlobalAllocator>: Send + Sync
where
    A: Allocator + UnwindSafe + Send + Sync + 'static,
{
    // Required methods
    fn nbits(&self) -> usize;
    fn bytes(&self) -> usize;
    fn dim(&self) -> usize;
    fn full_dim(&self) -> usize;
    fn distance_computer(
        &self,
        allocator: A,
    ) -> Result<DistanceComputer<A>, AllocatorError>;
    fn distance_computer_ref(&self) -> &dyn DynDistanceComputer;
    fn query_computer(
        &self,
        layout: QueryLayout,
        allocator: A,
    ) -> Result<DistanceComputer<A>, DistanceComputerError>;
    fn query_buffer_description(
        &self,
        layout: QueryLayout,
    ) -> Result<QueryBufferDescription, UnsupportedQueryLayout>;
    fn compress_query(
        &self,
        x: &[f32],
        layout: QueryLayout,
        allow_rescale: bool,
        buffer: OpaqueMut<'_>,
        scratch: ScopedAllocator<'_>,
    ) -> Result<(), QueryCompressionError>;
    fn fused_query_computer(
        &self,
        x: &[f32],
        layout: QueryLayout,
        allow_rescale: bool,
        allocator: A,
        scratch: ScopedAllocator<'_>,
    ) -> Result<QueryComputer<A>, QueryComputerError>;
    fn is_supported(&self, layout: QueryLayout) -> bool;
    fn compress(
        &self,
        x: &[f32],
        into: OpaqueMut<'_>,
        scratch: ScopedAllocator<'_>,
    ) -> Result<(), CompressionError>;
    fn metric(&self) -> SupportedMetric;
    fn try_clone_into(
        &self,
        allocator: A,
    ) -> Result<Poly<dyn Quantizer<A>, A>, AllocatorError>;
    fn serialize(&self, allocator: A) -> Result<Poly<[u8], A>, AllocatorError>;
}

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

This allows us to have a single [dyn Quantizer] type without generics while still supporting the range of bit-widths and query strategies we wish to support.

A level of indirection for each distance computation, unfortunately, is required to support this. But we try to structure the code so there is only a single level of indirection.

Allocator

The quantizer is parameterized by the allocator provided used to acquire any necessary memory for returned data structures. The contract is as follows:

1. Any allocation made as part of a returned data structure from a function will be performed through the allocator given to that function.

2. If dynamic memory allocation for scratch space is required, a separate scratch allocator will be required and all scratch space allocations will go through that allocator.

Required Methods

fn nbits(&self) -> usize

The effective number of bits in the encoding.

fn bytes(&self) -> usize

The number of bytes occupied by each compressed vector.

fn dim(&self) -> usize

The effective dimensionality of each compressed vector.

fn full_dim(&self) -> usize

The dimensionality of the full-precision input vectors.

fn distance_computer( &self, allocator: A, ) -> Result<DistanceComputer<A>, AllocatorError>

Return a distance computer capable on operating on validly initialized Opaque slices of length Self::bytes.

These slices should be initialized by Self::compress.

The query layout associated with this computer will always be QueryLayout::SameAsData.

fn distance_computer_ref(&self) -> &dyn DynDistanceComputer

Return a scoped distance computer capable on operating on validly initialized Opaque slices of length Self::bytes.

These slices should be initialized by Self::compress.

fn query_computer( &self, layout: QueryLayout, allocator: A, ) -> Result<DistanceComputer<A>, DistanceComputerError>

A stand alone distance computer specialized for the specified query layout.

Only layouts for which Self::is_supported returns true are supported.

Note

The returned object will only be compatible with queries compressed using Self::compress_query using the same layout. If possible, the API Self::fused_query_computer should be used to avoid this ambiguity.

fn query_buffer_description( &self, layout: QueryLayout, ) -> Result<QueryBufferDescription, UnsupportedQueryLayout>

Return the number of bytes and alignment of a buffer used to contain a compressed query with the provided layout.

Only layouts for which Self::is_supported returns true are supported.

fn compress_query( &self, x: &[f32], layout: QueryLayout, allow_rescale: bool, buffer: OpaqueMut<'_>, scratch: ScopedAllocator<'_>, ) -> Result<(), QueryCompressionError>

Compress the query using the specified layout into buffer.

This requires that buffer have the exact size and alignment as that returned from query_buffer_description.

Only layouts for which Self::is_supported returns true are supported.

fn fused_query_computer( &self, x: &[f32], layout: QueryLayout, allow_rescale: bool, allocator: A, scratch: ScopedAllocator<'_>, ) -> Result<QueryComputer<A>, QueryComputerError>

Return a query for the argument x capable on operating on validly initialized Opaque slices of length Self::bytes.

These slices should be initialized by Self::compress.

Note: Only layouts for which Self::is_supported returns true are supported.

fn is_supported(&self, layout: QueryLayout) -> bool

Return whether or not this plan supports the given QueryLayout.

fn compress( &self, x: &[f32], into: OpaqueMut<'_>, scratch: ScopedAllocator<'_>, ) -> Result<(), CompressionError>

Compress the vector x into the opaque slice.

Note

This requires the length of the slice to be exactly Self::bytes. There is no alignment restriction on the base pointer.

fn metric(&self) -> SupportedMetric

Return the metric this plan was created with.

fn try_clone_into( &self, allocator: A, ) -> Result<Poly<dyn Quantizer<A>, A>, AllocatorError>

Clone the backing object.

fn serialize(&self, allocator: A) -> Result<Poly<[u8], A>, AllocatorError>

Available on crate feature flatbuffers only.

Serialize self into a flatbuffer, returning the flatbuffer. The function try_deserialize should undo this operation.

Implementors

impl<A, B> Quantizer<B> for Impl<1, A>

where A: Allocator + RefUnwindSafe + Send + Sync + 'static, B: Allocator + UnwindSafe + Send + Sync + 'static,

impl<A, B> Quantizer<B> for Impl<2, A>

where A: Allocator + RefUnwindSafe + Send + Sync + 'static, B: Allocator + UnwindSafe + Send + Sync + 'static,

impl<A, B> Quantizer<B> for Impl<4, A>

where A: Allocator + RefUnwindSafe + Send + Sync + 'static, B: Allocator + UnwindSafe + Send + Sync + 'static,

impl<A, B> Quantizer<B> for Impl<8, A>

where A: Allocator + RefUnwindSafe + Send + Sync + 'static, B: Allocator + UnwindSafe + Send + Sync + 'static,