Struct CoarseCentroids 

pub struct CoarseCentroids {
    pub num_clusters: u32,
    pub dim: usize,
    pub centroids: Vec<f32>,
    pub version: u64,
    pub soar_config: Option<SoarConfig>,
    /* private fields */
}

Coarse centroids for IVF - trained once, shared across all segments

Fields

num_clusters: u32

Number of clusters

dim: usize

Vector dimension

centroids: Vec<f32>

Centroids stored as flat array (num_clusters × dim)

version: u64

Version for compatibility checking during merge

soar_config: Option<SoarConfig>

SOAR configuration (if enabled)

Implementations

impl CoarseCentroids

pub fn train( config: &CoarseConfig, vectors: &[Vec<f32>], index_label: &str, ) -> Self

Train coarse centroids using k-means algorithm

Uses deterministic adaptive D² seeding and Lloyd refinement.

pub fn find_nearest(&self, vector: &[f32]) -> u32

Find nearest cluster for a query vector

pub fn find_k_nearest(&self, vector: &[f32], k: usize) -> Vec<u32>

Find k nearest clusters for a query vector

pub fn probe( &self, vector: &[f32], k: usize, mode: IvfRoutingMode, ) -> IvfProbePlan

Build a versioned probe plan using flat or two-level routing.

The returned leaf IDs are independent of segment contents and can be reused across every segment built from this global codebook.

pub fn validate_routing(&self, mode: IvfRoutingMode) -> Result<(), String>

pub fn find_k_nearest_with_distances( &self, vector: &[f32], k: usize, ) -> Vec<(u32, f32)>

Find k nearest clusters with their distances

pub fn assign(&self, vector: &[f32]) -> MultiAssignment

Assign vector with SOAR (if configured) or standard assignment

pub fn assign_with_routing( &self, vector: &[f32], routing: IvfRoutingMode, ) -> MultiAssignment

Assign during segment construction through the same persisted router used at query time. Large codebooks therefore avoid an O(K) scan for every indexed vector.

pub fn assign_with_soar( &self, vector: &[f32], config: &SoarConfig, ) -> MultiAssignment

SOAR-style assignment: balance secondary distortion and residual orthogonality

pub fn get_centroid(&self, cluster_id: u32) -> &[f32]

Get centroid for a cluster

pub fn compute_residual(&self, vector: &[f32], cluster_id: u32) -> Vec<f32>

Compute residual vector (vector - centroid)

pub fn size_bytes(&self) -> usize

Memory usage in bytes

pub fn to_bytes(&self) -> Result<Vec<u8>>

Encode the current index-level centroid artifact format.

Trait Implementations

impl Clone for CoarseCentroids

fn clone(&self) -> CoarseCentroids

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CoarseCentroids

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CoarseCentroids

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for CoarseCentroids

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.