Struct QuantumClusterer 

pub struct QuantumClusterer { /* private fields */ }

Quantum-Inspired Clustering Algorithm

This structure implements a quantum-enhanced version of k-means clustering that uses quantum superposition for centroid representation and quantum interference effects to improve convergence. The algorithm maintains both classical and quantum representations of cluster centroids.

Features

• Quantum superposition for exploring multiple centroid configurations
• Quantum interference effects for enhanced convergence
• Quantum-enhanced distance calculations
• Configurable quantum circuit depth and superposition states

Example

use scirs2_core::ndarray::Array2;
use scirs2_spatial::quantum_inspired::algorithms::QuantumClusterer;

let points = Array2::from_shape_vec((6, 2), vec![
    0.0, 0.0, 1.0, 0.0, 0.0, 1.0,
    5.0, 5.0, 6.0, 5.0, 5.0, 6.0
]).unwrap();

let mut clusterer = QuantumClusterer::new(2)
    .with_quantum_depth(4)
    .with_superposition_states(16)
    .with_max_iterations(50);

let (centroids, assignments) = clusterer.fit(&points.view()).unwrap();

Implementations

impl QuantumClusterer

pub fn new(num_clusters: usize) -> Self

Create new quantum clusterer

Arguments

• num_clusters - Number of clusters to find

Returns

A new QuantumClusterer with default configuration

pub fn with_quantum_depth(self, depth: usize) -> Self

Configure quantum circuit depth

Higher depth allows for more complex quantum operations but increases computational cost. Typical values range from 3-10.

Arguments

• depth - Quantum circuit depth

pub fn with_superposition_states(self, states: usize) -> Self

Configure superposition states

Number of quantum superposition states to maintain during clustering. More states provide better exploration but increase memory usage.

Arguments

• states - Number of superposition states

pub fn with_max_iterations(self, max_iter: usize) -> Self

Configure maximum iterations

Maximum number of iterations for the quantum clustering algorithm.

Arguments

• max_iter - Maximum number of iterations

pub fn with_tolerance(self, tolerance: f64) -> Self

Configure convergence tolerance

Algorithm stops when the change in cost function is below this threshold.

Arguments

• tolerance - Convergence tolerance

pub fn fit( &mut self, points: &ArrayView2<'_, f64>, ) -> SpatialResult<(Array2<f64>, Array1<usize>)>

Fit quantum clustering to data points

Performs quantum-enhanced k-means clustering on the input points. Returns cluster centroids and point assignments.

Arguments

• points - Input points to cluster (n_points × n_dims)

Returns

Tuple of (centroids, assignments) where:

• centroids: Array of cluster centers (num_clusters × n_dims)
• assignments: Cluster assignment for each point (n_points,)

Errors

Returns error if number of points is less than number of clusters

pub fn predict( &self, points: &ArrayView2<'_, f64>, ) -> SpatialResult<Array1<usize>>

Predict cluster assignments for new points

Uses the fitted quantum centroids to assign cluster labels to new points.

Arguments

• points - New points to classify

Returns

Cluster assignments for the new points

Errors

Returns error if the clusterer hasn’t been fitted yet

pub fn num_clusters(&self) -> usize

Get number of clusters

pub fn quantum_depth(&self) -> usize

Get quantum circuit depth

pub fn superposition_states(&self) -> usize

Get number of superposition states

pub fn is_fitted(&self) -> bool

Check if the clusterer has been fitted

pub fn quantum_state(&self) -> Option<&QuantumState>

Get the quantum centroid state (if fitted)

Trait Implementations

impl Clone for QuantumClusterer

fn clone(&self) -> QuantumClusterer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for QuantumClusterer

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

Formats the value using the given formatter.