🎯 avx Clustering

State-of-the-art clustering algorithms for Rust - surpassing scikit-learn, HDBSCAN, and RAPIDS cuML

Pure Rust implementations of advanced clustering algorithms with GPU acceleration, parallel processing, and scientific features.

🚀 Features

Core Algorithms

• ✅ K-Means - Lloyd's algorithm with K-Means++ init, Mini-Batch variant
• ✅ DBSCAN - Density-based spatial clustering with KD-tree optimization
• ✅ HDBSCAN - Hierarchical DBSCAN with noise handling
• ✅ OPTICS - Ordering points for cluster structure
• ✅ Affinity Propagation - Message passing based clustering
• ✅ Mean Shift - Non-parametric feature-space analysis
• ✅ Spectral Clustering - Graph-based clustering with eigenvector decomposition
• ✅ Agglomerative - Hierarchical clustering (linkage methods)
• ✅ Ensemble Clustering - Consensus clustering for robustness

Advanced Features

• ✅ GPU Acceleration - CUDA & WGPU support for massive speedups
• ✅ Parallel Processing - Multi-threaded via Rayon
• ✅ Time Series Clustering - DTW distance, shape-based clustering
• ✅ Text Clustering - TF-IDF vectorization, cosine similarity
• ✅ Scientific - Astronomy (galaxy clustering), Physics (particle clustering), Spacetime (4D tensor clustering)
• ✅ Incremental Learning - Online clustering with streaming data
• ✅ Auto-tuning - Hyperparameter optimization

📦 Installation

[dependencies]
avx-clustering = "0.1"

Feature Flags

[dependencies]
avx-clustering = { version = "0.1", features = ["gpu"] }

Available features:

• gpu - CUDA GPU acceleration
• gpu-wgpu - WGPU cross-platform GPU support
• full - All features enabled

🎯 Quick Start

K-Means Clustering

use avx_clustering::prelude::*;
use ndarray::array;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create sample data
    let data = array![
        [1.0, 2.0],
        [1.5, 1.8],
        [5.0, 8.0],
        [8.0, 8.0],
        [1.0, 0.6],
        [9.0, 11.0],
    ];

    // Fit K-Means with 2 clusters
    let kmeans = KMeansBuilder::new(2)
        .max_iter(100)
        .tolerance(1e-4)
        .fit(data.view())?;

    println!("Labels: {:?}", kmeans.labels);
    println!("Centroids:\n{}", kmeans.centroids);

    // Predict new points
    let new_data = array![[0.0, 0.0], [10.0, 10.0]];
    let predictions = kmeans.predict(new_data.view())?;
    println!("Predictions: {:?}", predictions);

    Ok(())
}

DBSCAN - Density-Based Clustering

use avx_clustering::prelude::*;

let data = array![
    [1.0, 2.0],
    [2.0, 2.0],
    [2.0, 3.0],
    [8.0, 7.0],
    [8.0, 8.0],
    [25.0, 80.0], // Noise point
];

let dbscan = DBSCANBuilder::new()
    .eps(3.0)
    .min_samples(2)
    .fit(data.view())?;

println!("Labels: {:?}", dbscan.labels); // -1 indicates noise
println!("Core samples: {:?}", dbscan.core_sample_indices);

HDBSCAN - Hierarchical DBSCAN

use avx_clustering::prelude::*;

let data = generate_blobs(1000, 5, 2.0)?;

let hdbscan = HDBSCANBuilder::new()
    .min_cluster_size(50)
    .min_samples(5)
    .fit(data.view())?;

println!("Number of clusters: {}", hdbscan.n_clusters());
println!("Outlier scores: {:?}", &hdbscan.outlier_scores[..10]);

Spectral Clustering

use avx_clustering::prelude::*;

let data = generate_moons(300, 0.1)?; // Two interleaving half circles

let spectral = SpectralClusteringBuilder::new(2)
    .n_neighbors(10)
    .fit(data.view())?;

println!("Labels: {:?}", spectral.labels);

Affinity Propagation

use avx_clustering::prelude::*;

let data = array![
    [0.0, 0.0],
    [0.1, 0.1],
    [5.0, 5.0],
    [5.1, 5.1],
];

let ap = AffinityPropagationBuilder::new()
    .damping(0.5)
    .max_iter(200)
    .fit(data.view())?;

println!("Exemplars: {}", ap.cluster_centers);
println!("Number of clusters: {}", ap.n_clusters);

Ensemble Clustering

use avx_clustering::prelude::*;

let data = generate_blobs(500, 3, 1.0)?;

let ensemble = EnsembleClusteringBuilder::new(3)
    .n_iterations(20)
    .subsample_ratio(0.8)
    .fit(data.view())?;

println!("Stability score: {:.3}", ensemble.stability_score());
println!("Labels: {:?}", &ensemble.labels[..10]);

Time Series Clustering

use avx_clustering::prelude::*;

// Create time series data (n_series x n_timepoints)
let ts_data = array![
    [1.0, 2.0, 3.0, 4.0, 5.0],
    [1.1, 2.1, 3.1, 4.1, 5.1],
    [10.0, 9.0, 8.0, 7.0, 6.0],
];

let ts_kmeans = TimeSeriesKMeansBuilder::new(2)
    .distance_metric(TimeSeriesDistance::DTW)
    .fit(ts_data.view())?;

println!("Time series clusters: {:?}", ts_kmeans.labels);

Text Clustering

use avx_clustering::prelude::*;

let documents = vec![
    "machine learning algorithms",
    "deep neural networks",
    "clustering data points",
    "supervised learning models",
];

let text_cluster = TextClusteringBuilder::new(2)
    .max_features(100)
    .fit(&documents)?;

println!("Document clusters: {:?}", text_cluster.labels);

📊 Performance Benchmarks

Hardware: AMD Ryzen 9 5950X, RTX 3090

Comparison with Other Libraries (100K points, K-Means):

🎓 Examples

Galaxy Clustering (Astronomy)

use avx_clustering::scientific::astronomy::*;

// Load astronomical data (RA, Dec, redshift)
let galaxies = load_sdss_data("galaxies.csv")?;

let galaxy_clusters = GalaxyClusteringBuilder::new()
    .min_members(10)
    .max_radius_mpc(2.0)
    .fit(galaxies.view())?;

println!("Found {} galaxy clusters", galaxy_clusters.n_clusters());

Particle Clustering (Physics)

use avx_clustering::scientific::physics::*;

// Particle collision data (px, py, pz, energy)
let particles = simulate_collision()?;

let jets = ParticleClusteringBuilder::new()
    .algorithm(JetAlgorithm::AntiKt)
    .radius_parameter(0.4)
    .fit(particles.view())?;

println!("Reconstructed {} jets", jets.n_clusters());

Incremental Clustering (Streaming Data)

use avx_clustering::prelude::*;

let mut incremental = IncrementalKMeans::new(3);

// Process data in batches
for batch in data_stream.chunks(100) {
    incremental.partial_fit(batch.view())?;
}

println!("Final centroids:\n{}", incremental.centroids);

🔬 Advanced Usage

GPU Acceleration

use avx_clustering::gpu::*;

#[cfg(feature = "gpu")]
{
    let data = generate_large_dataset(10_000_000)?;

    let kmeans_gpu = KMeansGPU::new(10)
        .fit(data.view())?;

    println!("GPU clustering complete: {} clusters", kmeans_gpu.n_clusters);
}

Auto-Tuning

use avx_clustering::prelude::*;

let data = generate_complex_data()?;

// Automatically find best number of clusters
let optimal = auto_tune_kmeans(data.view(), 2..=10)?;

println!("Optimal k: {}", optimal.k);
println!("Silhouette score: {:.3}", optimal.score);

Custom Distance Metrics

use avx_clustering::metrics::*;

fn custom_distance(a: &[f64], b: &[f64]) -> f64 {
    // Your custom distance function
    a.iter().zip(b.iter())
        .map(|(x, y)| (x - y).abs())
        .sum()
}

let dbscan = DBSCANBuilder::new()
    .eps(3.0)
    .min_samples(5)
    .distance_fn(custom_distance)
    .fit(data.view())?;

🧪 Testing

# Run all tests
cargo test

# Run with all features
cargo test --all-features

# Run benchmarks
cargo bench

# Run specific algorithm tests
cargo test --test kmeans
cargo test --test dbscan

📈 Benchmarks

# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench --bench kmeans_bench

# With GPU
cargo bench --features gpu --bench gpu_benchmarks

🏗️ Architecture

avx-clustering/
├── algorithms/         # Core clustering algorithms
│   ├── kmeans.rs
│   ├── dbscan.rs
│   ├── hdbscan.rs
│   ├── optics.rs
│   ├── affinity_propagation.rs
│   ├── mean_shift.rs
│   ├── spectral.rs
│   ├── agglomerative.rs
│   ├── ensemble.rs
│   ├── text.rs
│   └── timeseries.rs
├── gpu/                # GPU implementations
│   ├── kmeans_gpu.rs
│   └── dbscan_gpu.rs
├── metrics/            # Distance metrics & evaluation
│   ├── distances.rs
│   ├── silhouette.rs
│   └── davies_bouldin.rs
└── scientific/         # Domain-specific clustering
    ├── astronomy.rs    # Galaxy clustering
    ├── physics.rs      # Particle clustering
    └── spacetime.rs    # 4D tensor clustering

🎯 Use Cases

Customer Segmentation

let customer_features = extract_features(&customers)?;
let segments = KMeansBuilder::new(5).fit(customer_features.view())?;

Anomaly Detection

let dbscan = DBSCANBuilder::new().eps(0.3).min_samples(5).fit(data.view())?;
let anomalies: Vec<_> = dbscan.labels.iter()
    .enumerate()
    .filter(|(_, &label)| label == -1)
    .map(|(i, _)| i)
    .collect();

Image Segmentation

let pixels = image_to_array(&img)?;
let segments = MeanShiftBuilder::new().bandwidth(2.0).fit(pixels.view())?;

Document Clustering

let docs = load_documents("corpus.txt")?;
let clusters = TextClusteringBuilder::new(10)
    .max_features(1000)
    .fit(&docs)?;

📚 Documentation

• API Docs: https://docs.rs/avx-clustering
• Guide: https://avila.inc/docs/clustering
• Examples: examples/
• Benchmarks: benches/

🔬 Comparison with Other Libraries

🛣️ Roadmap

• K-Means, DBSCAN, HDBSCAN, OPTICS
• Affinity Propagation, Mean Shift, Spectral
• Ensemble clustering
• GPU acceleration (CUDA)
• More linkage methods for Agglomerative
• BIRCH algorithm
• CURE algorithm
• Fuzzy C-Means
• Subspace clustering
• Distributed clustering (multi-node)

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md.

📧 Contact

• Website: https://avila.inc
• Email: dev@avila.inc
• GitHub: https://github.com/avilaops/arxis

Built with ❤️ in Brazil by avx Team