umap_rs/lib.rs
1//! Fast, parallel Rust implementation of the UMAP dimensionality reduction algorithm.
2//!
3//! This library provides a streamlined implementation of UMAP (Uniform Manifold
4//! Approximation and Projection) focused on performance and correctness. It requires
5//! precomputed k-nearest neighbors and initialization, allowing you to use your
6//! preferred libraries for these steps.
7//!
8//! # Example
9//!
10//! ```ignore
11//! use umap::{Umap, UmapConfig};
12//! use umap::EuclideanMetric;
13//!
14//! // Configure UMAP
15//! let config = UmapConfig::default();
16//! let umap = Umap::new(config);
17//!
18//! // Fit to data (requires precomputed KNN and initialization)
19//! let model = umap.fit(
20//! data.view(),
21//! knn_indices.view(),
22//! knn_dists.view(),
23//! init.view(),
24//! );
25//!
26//! // Get the embedding
27//! let embedding = model.embedding();
28//! ```
29//!
30//! # Features
31//!
32//! - **Parallel optimization**: Rayon's parallel SGD (Hogwild! algorithm)
33//! - **Extensible metrics**: Custom distance functions via the `Metric` trait
34//! - **Zero-copy views**: Efficient array handling with `ndarray`
35//!
36//! # Limitations
37//!
38//! - Dense arrays only (no sparse matrix support)
39//! - Fit only (transform for new points not yet implemented)
40//! - Panics on invalid input (no Result-based error handling)
41//! - Requires external KNN computation and initialization
42//!
43//! # Public API
44//!
45//! The library exposes a minimal, well-defined API:
46//!
47//! * [`Umap`] - Main algorithm struct
48//! * [`FittedUmap`] - Fitted model with embeddings
49//! * [`UmapConfig`] - Configuration parameters
50//! * [`Metric`] - Distance metric trait
51//! * [`EuclideanMetric`] - Euclidean distance implementation
52
53// Public modules
54pub mod config;
55pub mod metric;
56
57// Public re-exports (primary API)
58pub use config::GraphParams;
59pub use config::ManifoldParams;
60pub use config::OptimizationParams;
61pub use config::UmapConfig;
62pub use embedding::FittedUmap;
63pub use embedding::Umap;
64pub use manifold::LearnedManifold;
65pub use metric::Metric;
66pub use metric::MetricType;
67pub use optimizer::Optimizer;
68pub use umap::SparseMat;
69
70// Internal modules (not exposed)
71mod distances;
72mod embedding;
73mod layout;
74mod umap;
75mod utils;
76
77// Public modules (for advanced users)
78pub mod manifold;
79pub mod optimizer;
80
81// Re-export distances for convenience
82pub use distances::EuclideanMetric;
83
84// Tests
85#[cfg(test)]
86mod tests;