Struct FastKMeans 

pub struct FastKMeans { /* private fields */ }

Fast k-means clustering implementation compatible with ndarray.

This implementation uses double-chunking to process large datasets efficiently without running out of memory. It provides an API similar to FAISS and scikit-learn.

Example

use fastkmeans_rs::FastKMeans;
use ndarray::Array2;
use ndarray_rand::RandomExt;
use ndarray_rand::rand_distr::Uniform;

// Generate random data
let data = Array2::random((1000, 128), Uniform::new(-1.0f32, 1.0));

// Create and train the model
let mut kmeans = FastKMeans::new(128, 10);
kmeans.train(&data.view()).unwrap();

// Get cluster assignments
let labels = kmeans.predict(&data.view()).unwrap();

Implementations

impl FastKMeans

pub fn new(d: usize, k: usize) -> FastKMeans

Create a new FastKMeans instance with default configuration.

Arguments

• d - Number of features (dimensions) in the data
• k - Number of clusters

Panics

Panics if k is 0.

pub fn with_config(config: KMeansConfig) -> FastKMeans

Create a new FastKMeans instance with custom configuration.

Arguments

• config - Custom configuration for the k-means algorithm

Panics

Panics if config.k is 0.

pub fn train( &mut self, data: &ArrayBase<ViewRepr<&f32>, Dim<[usize; 2]>>, ) -> Result<(), KMeansError>

Train the k-means model on the given data.

This method mimics the FAISS train() API.

Arguments

• data - Training data of shape (n_samples, n_features)

Errors

Returns an error if:

• Number of samples is less than k
• Data dimensions don’t match (for subsequent calls)

pub fn fit( &mut self, data: &ArrayBase<ViewRepr<&f32>, Dim<[usize; 2]>>, ) -> Result<&mut FastKMeans, KMeansError>

Fit the model to the data.

This method mimics the scikit-learn fit() API. It is equivalent to train().

Arguments

• data - Training data of shape (n_samples, n_features)

Returns

Returns &mut Self for method chaining.

pub fn predict( &self, data: &ArrayBase<ViewRepr<&f32>, Dim<[usize; 2]>>, ) -> Result<ArrayBase<OwnedRepr<i64>, Dim<[usize; 1]>>, KMeansError>

Predict cluster assignments for new data.

This method mimics the scikit-learn predict() API.

Arguments

• data - Data to predict, of shape (n_samples, n_features)

Returns

Returns an array of cluster labels of shape (n_samples,).

Errors

Returns an error if:

• The model has not been fitted yet
• Data dimensions don’t match the training data

pub fn fit_predict( &mut self, data: &ArrayBase<ViewRepr<&f32>, Dim<[usize; 2]>>, ) -> Result<ArrayBase<OwnedRepr<i64>, Dim<[usize; 1]>>, KMeansError>

Fit the model and predict cluster assignments in one call.

This method mimics the scikit-learn fit_predict() API.

Arguments

• data - Training data of shape (n_samples, n_features)

Returns

Returns an array of cluster labels of shape (n_samples,).

pub fn centroids(&self) -> Option<&ArrayBase<OwnedRepr<f32>, Dim<[usize; 2]>>>

Get the centroids of the fitted model.

Returns

Returns Some(&Array2<f32>) if the model has been fitted, None otherwise.

pub fn k(&self) -> usize

Get the number of clusters.

pub fn d(&self) -> usize

Get the number of features (dimensions).

pub fn config(&self) -> &KMeansConfig

Get the configuration.