Struct ClusterIndex 

pub struct ClusterIndex { /* private fields */ }

K-means clustering index supporting ANN search by cluster probing.

Implementations

impl ClusterIndex

pub fn new(k: usize, max_iter: usize) -> Self

Create a new index.

• k — number of clusters (must be ≥ 1)
• max_iter — maximum Lloyd iterations when build is called

pub fn num_clusters(&self) -> usize

Current number of clusters.

pub fn len(&self) -> usize

Current number of stored vectors.

pub fn is_empty(&self) -> bool

Return true when no vectors have been inserted.

pub fn insert( &mut self, id: String, vector: Vec<f32>, ) -> Result<(), ClusterError>

Insert a vector into the index, assigning it to the nearest centroid.

If no clustering has been built yet (centroids is empty), the vector is stored without a valid cluster assignment and an initial cluster will be assigned during build.

Returns an error when:

• The id is already present.
• The vector dimensionality is inconsistent with existing vectors.

pub fn build(&mut self) -> Result<(), ClusterError>

Run Lloyd’s K-means algorithm to assign all vectors to clusters.

Initialisation: k-means++ style — first centroid chosen as the first vector, subsequent centroids chosen as the furthest from the current set.

pub fn assign(&self, query: &[f32]) -> Option<usize>

Return the index of the centroid nearest to query.

pub fn cluster_stats( &self, cluster_id: usize, ) -> Result<ClusterStats, ClusterError>

Return statistics for the cluster with the given id.

pub fn all_cluster_stats(&self) -> Vec<ClusterStats>

Return statistics for all clusters.

pub fn merge_clusters(&mut self, a: usize, b: usize) -> Result<(), ClusterError>

Merge clusters a and b into a single cluster.

The merged centroid is the weighted mean of the two cluster centroids. All members of both clusters are reassigned to the lower id; the higher id slot is removed by swapping with the last centroid and truncating.

pub fn merge_closest_clusters(&mut self) -> Result<(), ClusterError>

Merge the two closest clusters (by centroid distance).

pub fn split_largest_cluster(&mut self) -> Result<(), ClusterError>

Split the largest cluster into two by creating a new centroid displaced by the principal direction (first PCA component approximated as the direction of greatest variance along each axis).

The new centroid is appended to the end; half the members are re-assigned to it.

pub fn search( &self, query: &[f32], top_k: usize, n_probes: usize, ) -> Result<Vec<(String, f32)>, ClusterError>

Search for the top_k nearest vectors to query by probing the n_probes closest cluster centroids.

Returns a list of (id, distance) pairs sorted by ascending distance.

Trait Implementations

impl Clone for ClusterIndex

fn clone(&self) -> ClusterIndex

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClusterIndex

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

Formats the value using the given formatter.