pub(crate) mod prng;
pub(crate) mod qam_lloyd_max;
pub(crate) mod qam_sliding;
pub(crate) mod upq;
use crate::{
error::{Error, Result},
format::catalog::{CodecFamily, VectorMetric},
};
pub use crate::format::qam_lloyd_max_params::QamLloydMaxParams;
pub use crate::format::upq_params::{UpqDesignSource, UpqParams};
#[derive(Clone, Debug, PartialEq)]
pub enum CodecParams {
QamLloydMax(QamLloydMaxParams),
Upq(UpqParams),
}
impl CodecParams {
pub fn family(&self) -> CodecFamily {
match self {
CodecParams::QamLloydMax(_) => CodecFamily::QamLloydMax,
CodecParams::Upq(_) => CodecFamily::Upq,
}
}
pub(crate) fn wire_version(&self) -> u16 {
match self {
CodecParams::QamLloydMax(_) => 1,
CodecParams::Upq(_) => 1,
}
}
pub(crate) fn family_discriminant(&self) -> u32 {
match self {
CodecParams::QamLloydMax(_) => 1,
CodecParams::Upq(_) => 2,
}
}
pub fn dimension(&self) -> u32 {
match self {
CodecParams::QamLloydMax(p) => p.dimension,
CodecParams::Upq(p) => p.dimension,
}
}
pub(crate) fn encode(&self) -> Result<Vec<u8>> {
match self {
CodecParams::QamLloydMax(p) => {
crate::format::qam_lloyd_max_params::encode_qam_lloyd_max_params(p)
}
CodecParams::Upq(p) => crate::format::upq_params::encode_upq_params(p),
}
}
pub(crate) fn decode(family: CodecFamily, bytes: &[u8]) -> Result<Self> {
match family {
CodecFamily::QamLloydMax => Ok(CodecParams::QamLloydMax(
crate::format::qam_lloyd_max_params::decode_qam_lloyd_max_params(bytes)?,
)),
CodecFamily::Upq => Ok(CodecParams::Upq(
crate::format::upq_params::decode_upq_params(bytes)?,
)),
CodecFamily::_LegacyInt4PcaZero => Err(Error::Unsupported(
"CodecParams::decode: the Int4PcaZero family was removed in v2.2; \
rebuild the .vls with a current codec"
.into(),
)),
}
}
pub(crate) fn instantiate(&self) -> Result<Box<dyn VectorCodec>> {
Ok(match self {
CodecParams::QamLloydMax(p) => {
Box::new(qam_lloyd_max::QamLloydMaxCodec::from_params(p)?)
}
CodecParams::Upq(p) => Box::new(upq::UpqCodec::from_params(p)?),
})
}
}
#[cfg(any(test, feature = "bench"))]
pub mod simd_bench {
use crate::codec::qam_lloyd_max::simd;
#[inline(always)]
pub fn asymmetric_dot_pairs(
q_rot: &[f32],
amp_indices: &[u32],
phase_indices: &[u32],
sigma_per_pair: &[f32],
amp_levels_unit: &[f32],
phase_cos_lut: &[f32],
phase_sin_lut: &[f32],
) -> (f32, f32) {
simd::asymmetric_dot_pairs(
q_rot,
amp_indices,
phase_indices,
sigma_per_pair,
amp_levels_unit,
phase_cos_lut,
phase_sin_lut,
)
}
#[inline(always)]
pub fn scalar_asymmetric_dot_pairs(
q_rot: &[f32],
amp_indices: &[u32],
phase_indices: &[u32],
sigma_per_pair: &[f32],
amp_levels_unit: &[f32],
phase_cos_lut: &[f32],
phase_sin_lut: &[f32],
) -> (f32, f32) {
simd::scalar_asymmetric_dot_pairs(
q_rot,
amp_indices,
phase_indices,
sigma_per_pair,
amp_levels_unit,
phase_cos_lut,
phase_sin_lut,
)
}
#[inline(always)]
pub fn block_hadamard_forward(data: &mut [f32], signs: &[f32], block_size: usize) {
simd::block_hadamard_forward(data, signs, block_size)
}
#[inline(always)]
pub fn scalar_block_hadamard_forward(data: &mut [f32], signs: &[f32], block_size: usize) {
simd::scalar_block_hadamard_forward(data, signs, block_size)
}
#[inline(always)]
pub fn block_hadamard_inverse(data: &mut [f32], signs: &[f32], block_size: usize) {
simd::block_hadamard_inverse(data, signs, block_size)
}
#[inline(always)]
pub fn scalar_block_hadamard_inverse(data: &mut [f32], signs: &[f32], block_size: usize) {
simd::scalar_block_hadamard_inverse(data, signs, block_size)
}
#[inline(always)]
pub fn pair_magnitudes(pairs: &[f32], mags: &mut [f32]) {
simd::pair_magnitudes(pairs, mags)
}
#[inline(always)]
pub fn scalar_pair_magnitudes(pairs: &[f32], mags: &mut [f32]) {
simd::scalar_pair_magnitudes(pairs, mags)
}
}
#[cfg(any(test, feature = "bench"))]
pub struct QamLloydMaxBench {
inner: qam_lloyd_max::QamLloydMaxCodec,
}
#[cfg(any(test, feature = "bench"))]
impl QamLloydMaxBench {
pub fn new(dim: usize) -> Result<Self> {
Ok(Self {
inner: qam_lloyd_max::QamLloydMaxCodec::new(dim)?,
})
}
pub fn with_config(
dim: usize,
block_size: usize,
amp_bits: u8,
phase_bits: u8,
renormalize_at_decode: bool,
) -> Result<Self> {
Ok(Self {
inner: qam_lloyd_max::QamLloydMaxCodec::with_config(
dim,
block_size,
amp_bits,
phase_bits,
renormalize_at_decode,
)?,
})
}
pub fn calibrate(&mut self, sample: &[Vec<f32>]) -> Result<()> {
self.inner.calibrate(sample)
}
pub fn to_params(&self, calibration_id: crate::format::Checksum) -> QamLloydMaxParams {
self.inner.to_params(calibration_id)
}
pub fn dim(&self) -> usize {
self.inner.dim
}
pub fn num_pairs(&self) -> usize {
self.inner.num_pairs
}
pub fn amp_bits(&self) -> u8 {
self.inner.amp_bits
}
pub fn phase_bits(&self) -> u8 {
self.inner.phase_bits
}
pub fn renormalize_at_decode(&self) -> bool {
self.inner.renormalize_at_decode
}
pub fn base_bytes_per_vector(&self) -> usize {
self.inner.base_bytes_per_vector
}
pub fn query_bytes_per_vector(&self) -> usize {
self.inner.query_bytes_per_vector
}
pub fn encode(&self, vector: &[f32]) -> Result<Vec<u8>> {
self.inner.encode(vector)
}
pub fn decode_lossy(&self, base: &[u8]) -> Result<Vec<f32>> {
self.inner.decode_lossy(base)
}
pub fn symmetric_distance(&self, a: &[u8], b: &[u8]) -> Result<f32> {
self.inner
.symmetric_distance(a, b, crate::format::catalog::VectorMetric::Cosine)
}
pub fn prepare_query(&self, query: &[f32]) -> Result<Vec<u8>> {
self.inner.prepare_query_blob(query)
}
pub fn rotate(&self, vector: &[f32]) -> Result<Vec<f32>> {
Ok(self.inner.prepare_query_rotated(vector)?.0)
}
pub fn asymmetric_distance_prepared(&self, q_blob: &[u8], base: &[u8]) -> Result<f32> {
self.inner.asymmetric_distance_prepared_blob(
q_blob,
base,
crate::format::catalog::VectorMetric::Cosine,
)
}
pub fn sliding(&self) -> Result<SlidingBench> {
Ok(SlidingBench {
eng: qam_sliding::QamSlidingEngine::from_codec(&self.inner)?,
})
}
}
#[cfg(any(test, feature = "bench"))]
pub struct SlidingBench {
eng: qam_sliding::QamSlidingEngine,
}
#[cfg(any(test, feature = "bench"))]
pub struct SlidingPrep {
prep: qam_sliding::QamSlidingPreparedQuery,
}
#[cfg(any(test, feature = "bench"))]
impl SlidingBench {
pub fn prepare(&self, query: &[f32]) -> Result<SlidingPrep> {
Ok(SlidingPrep {
prep: self.eng.prepare_query(query)?,
})
}
pub fn y_hat_norm(&self, base: &[u8]) -> f32 {
self.eng.y_hat_norm(base)
}
pub fn score_with_norm(&self, p: &SlidingPrep, base: &[u8], y_hat_norm: f32) -> Result<f32> {
self.eng
.asymmetric_distance_with_norm(&p.prep, base, y_hat_norm)
}
pub fn raw_dot_int(&self, p: &SlidingPrep, base: &[u8]) -> i64 {
self.eng.raw_dot_int(&p.prep, base)
}
pub fn raw_dot_int_scalar(&self, p: &SlidingPrep, base: &[u8]) -> i64 {
let amp_stream = &base
[self.eng.amp_stream_offset..self.eng.amp_stream_offset + self.eng.amp_stream_bytes];
let phase_stream = &base[self.eng.phase_stream_offset
..self.eng.phase_stream_offset + self.eng.phase_stream_bytes];
self.eng
.raw_dot_int_scalar(amp_stream, phase_stream, &p.prep.q_i8)
}
}
pub(crate) trait VectorCodec: Send + Sync {
fn as_any(&self) -> &dyn std::any::Any;
fn family(&self) -> CodecFamily;
fn dimension(&self) -> u32;
fn base_bytes_per_vector(&self) -> usize;
fn sign_sketch(&self, base: &[u8]) -> Result<Vec<u64>>;
fn encode(&self, values: &[f32]) -> Result<Vec<u8>>;
fn decode_lossy(&self, base: &[u8]) -> Result<Vec<f32>>;
fn asymmetric_distance(&self, query: &[f32], base: &[u8], metric: VectorMetric) -> Result<f32>;
fn prepare_query(&self, query: &[f32]) -> Result<Box<dyn std::any::Any + Send + Sync>> {
Ok(Box::new(query.to_vec()))
}
fn asymmetric_distance_prepared(
&self,
ctx: &(dyn std::any::Any + Send + Sync),
base: &[u8],
metric: VectorMetric,
) -> Result<f32> {
let query = ctx.downcast_ref::<Vec<f32>>().ok_or_else(|| {
crate::error::Error::Integrity(
"asymmetric_distance_prepared: default impl expects Vec<f32> ctx".into(),
)
})?;
self.asymmetric_distance(query, base, metric)
}
}