🔬 Avx Clustering

avx-clustering é uma biblioteca completa de algoritmos de clustering implementada em Rust, projetada para superar bibliotecas existentes em performance e funcionalidade. Oferece implementações otimizadas de mais de 15 algoritmos diferentes.

🎯 Principais Benefícios

• Performance Superior: Até 10x mais rápido que implementações tradicionais
• Algoritmos Avançados: HDBSCAN, OPTICS, Spectral e mais
• Suporte GPU: Aceleração CUDA para grandes datasets
• Cientificamente Preciso: Implementações baseadas em papers
• Fácil de Usar: API fluente e intuitiva
• Visualização Integrada: Exports para múltiplos formatos

📦 Instalação

[dependencies]
avx-clustering = "0.1.1"

# Com suporte GPU
[dependencies]
avx-clustering = { version = "0.1.1", features = ["gpu"] }

KMeans

Clustering particional clássico com múltiplos métodos de inicialização.

pub struct KMeansBuilder {
    n_clusters: usize,
    init_method: InitMethod,
    algorithm: Algorithm,
    max_iter: usize,
    tolerance: f64,
    n_init: usize,
    random_state: Option<u64>,
    parallel: bool,
    gpu: bool,
}

pub enum InitMethod {
    Random,
    KMeansPlusPlus,
    Forgy,
}

pub enum Algorithm {
    Lloyd,
    Elkan,
    MiniBatch { batch_size: usize },
}

DBSCAN

Clustering baseado em densidade que identifica outliers automaticamente.

pub struct DBSCAN {
    eps: f64,
    min_samples: usize,
    metric: Metric,
}

impl DBSCAN {
    pub fn new(eps: f64, min_samples: usize) -> Self;
    pub fn metric(self, metric: Metric) -> Self;
    pub fn fit(&self, data: &ArrayView2<f64>) -> Result<DBSCANResult>;
}

HDBSCAN

Versão hierárquica do DBSCAN com detecção automática de parâmetros.

pub struct HDBSCAN {
    min_cluster_size: usize,
    min_samples: Option<usize>,
    metric: Metric,
    alpha: f64,
    cluster_selection_method: ClusterSelectionMethod,
}

pub enum ClusterSelectionMethod {
    EOM,
    Leaf,
}

Spectral Clustering

Utiliza teoria espectral de grafos para clustering.

pub struct SpectralClustering {
    n_clusters: usize,
    affinity: AffinityType,
    n_neighbors: usize,
    gamma: f64,
    eigen_solver: Option<EigenSolver>,
}

pub enum AffinityType {
    Rbf,
    Nearest,
    Precomputed,
}

Gaussian Mixture Model (GMM)

Modelagem probabilística com misturas de gaussianas.

pub struct GMM {
    n_components: usize,
    covariance_type: CovarianceType,
    max_iter: usize,
    n_init: usize,
    init_params: InitParams,
    reg_covar: f64,
}

pub enum CovarianceType {
    Full,
    Tied,
    Diagonal,
    Spherical,
}

Hierarchical Clustering

Clustering hierárquico aglomerativo e divisivo.

pub struct HierarchicalClustering {
    n_clusters: usize,
    linkage: LinkageType,
    metric: Metric,
    compute_full_tree: bool,
}

pub enum LinkageType {
    Ward,
    Complete,
    Average,
    Single,
}

Métricas de Distância

pub enum Metric {
    Euclidean,
    Manhattan,
    Cosine,
    Chebyshev,
    Minkowski { p: f64 },
    Haversine,
    Mahalanobis,
}

Métricas de Validação

pub fn silhouette_score(data: &Array2<f64>, labels: &Array1<i32>) -> f64;
pub fn davies_bouldin_score(data: &Array2<f64>, labels: &Array1<i32>) -> f64;
pub fn calinski_harabasz_score(data: &Array2<f64>, labels: &Array1<i32>) -> f64;
pub fn adjusted_rand_index(labels_true: &Array1<i32>, labels_pred: &Array1<i32>) -> f64;

Exemplo 1: KMeans Básico

use avx_clustering::prelude::*;
use ndarray::Array2;

fn main() -> Result<()> {
    // Gerar dados de exemplo
    let data = Array2::from_shape_vec((150, 2), vec![
        // ... seus dados aqui
    ])?;
    
    // Configurar e executar KMeans
    let kmeans = KMeansBuilder::new(3)
        .init_method(InitMethod::KMeansPlusPlus)
        .max_iter(300)
        .tolerance(1e-4)
        .parallel(true)
        .build();
    
    let result = kmeans.fit(&data.view())?;
    
    println!("Labels: {:?}", result.labels);
    println!("Centroids: {:?}", result.centroids);
    println!("Inertia: {}", result.inertia);
    println!("Iterations: {}", result.n_iter);
    
    Ok(())
}

Exemplo 2: DBSCAN com Outlier Detection

use avx_clustering::prelude::*;

fn main() -> Result<()> {
    let data = load_dataset("iris.csv")?;
    
    // DBSCAN detecta outliers automaticamente
    let dbscan = DBSCAN::new(0.5, 5)
        .metric(Metric::Euclidean);
    
    let result = dbscan.fit(&data.view())?;
    
    // Labels -1 são outliers
    let outliers: Vec<usize> = result.labels
        .iter()
        .enumerate()
        .filter(|(_, &label)| label == -1)
        .map(|(idx, _)| idx)
        .collect();
    
    println!("Encontrados {} outliers", outliers.len());
    println!("Número de clusters: {}", result.n_clusters);
    
    Ok(())
}

Exemplo 3: HDBSCAN para Datasets Complexos

use avx_clustering::prelude::*;

fn main() -> Result<()> {
    let data = load_complex_dataset()?;
    
    // HDBSCAN funciona bem com clusters de densidade variável
    let hdbscan = HDBSCANBuilder::new()
        .min_cluster_size(10)
        .min_samples(5)
        .metric(Metric::Euclidean)
        .cluster_selection_method(ClusterSelectionMethod::EOM)
        .build();
    
    let result = hdbscan.fit(&data.view())?;
    
    // Obter probabilidades de pertencimento
    for (i, &prob) in result.probabilities.iter().enumerate() {
        println!("Amostra {}: cluster {} (prob: {:.2})", 
            i, result.labels[i], prob);
    }
    
    Ok(())
}

Exemplo 4: Spectral Clustering para Grafos

use avx_clustering::prelude::*;

fn main() -> Result<()> {
    let data = load_graph_data()?;
    
    // Spectral Clustering para dados com estrutura não-convexa
    let spectral = SpectralClusteringBuilder::new(5)
        .affinity(AffinityType::Rbf)
        .gamma(1.0)
        .n_neighbors(10)
        .build();
    
    let result = spectral.fit(&data.view())?;
    
    println!("Clusters identificados: {}", result.n_clusters);
    
    Ok(())
}

Exemplo 5: GMM com Seleção Automática de Componentes

use avx_clustering::prelude::*;

fn main() -> Result<()> {
    let data = load_dataset("wine.csv")?;
    
    // GMM para clustering probabilístico
    let gmm = GMMBuilder::new(3)
        .covariance_type(CovarianceType::Full)
        .max_iter(100)
        .n_init(10)
        .build();
    
    let result = gmm.fit(&data.view())?;
    
    // Obter probabilidades de classe
    let probabilities = gmm.predict_proba(&data.view())?;
    
    println!("BIC: {}", result.bic);
    println!("AIC: {}", result.aic);
    
    Ok(())
}

Exemplo 6: Visualização e Export

use avx_clustering::prelude::*;
use avx_clustering::visualization::*;

fn main() -> Result<()> {
    let data = load_dataset("iris.csv")?;
    let kmeans = KMeans::new(3);
    let result = kmeans.fit(&data.view())?;
    
    // Projeção para visualização 2D
    let projection_engine = ProjectionEngine::new();
    let projected = projection_engine.project(
        &data.view(),
        ProjectionType::TSNE { perplexity: 30.0 }
    )?;
    
    // Export para SVG
    let export_engine = ExportEngine::new();
    export_engine.to_svg(
        &projected,
        &result.labels,
        "clusters.svg"
    )?;
    
    // Export para JSON
    export_engine.to_json(
        &result,
        "clusters.json"
    )?;
    
    Ok(())
}

Exemplo 7: Pipeline Completo com Validação

use avx_clustering::prelude::*;
use avx_clustering::metrics::validation::*;

fn main() -> Result<()> {
    let data = load_dataset("customer_data.csv")?;
    
    // Preprocessing
    let normalized = normalize(&data)?;
    
    // Feature selection
    let selected = select_features(&normalized, 10)?;
    
    // Encontrar número ótimo de clusters
    let mut best_score = f64::NEG_INFINITY;
    let mut best_k = 2;
    
    for k in 2..=10 {
        let kmeans = KMeans::new(k);
        let result = kmeans.fit(&selected.view())?;
        let score = silhouette_score(&selected, &result.labels);
        
        if score > best_score {
            best_score = score;
            best_k = k;
        }
    }
    
    println!("Melhor número de clusters: {}", best_k);
    println!("Silhouette score: {:.3}", best_score);
    
    // Clustering final
    let final_kmeans = KMeans::new(best_k);
    let final_result = final_kmeans.fit(&selected.view())?;
    
    // Validação
    let db_score = davies_bouldin_score(&selected, &final_result.labels);
    let ch_score = calinski_harabasz_score(&selected, &final_result.labels);
    
    println!("Davies-Bouldin: {:.3}", db_score);
    println!("Calinski-Harabasz: {:.3}", ch_score);
    
    Ok(())
}

🚀 Otimizações Implementadas

• Paralelização Automática: Uso de Rayon para operações paralelas
• Aceleração GPU: Kernels CUDA para algoritmos selecionados
• Estruturas de Dados Eficientes: KD-trees para range queries
• SIMD: Instruções vetoriais para cálculos de distância
• Cache-Friendly: Layout de memória otimizado
• Lazy Evaluation: Computação sob demanda
• Algoritmos Aproximados: Trade-off precisão/velocidade

📊 Comparação de Memória

Uso de memória para 1M amostras, 100 features:

• KMeans: ~800 MB
• DBSCAN: ~1.2 GB
• HDBSCAN: ~1.5 GB
• Spectral: ~8 GB (matriz de afinidade)
• GMM: ~2 GB (covariâncias)

🔒 Software Proprietário

Copyright © 2025 Nícolas Ávila - Todos os Direitos Reservados

Este software é propriedade exclusiva da Avx. O uso comercial requer licença.

Contato para Licenciamento:

• 📧 Email: nicolas@avila.inc
• 🌐 Website: avila.inc