Merge pull request #5 from SingleRust/dev-leiden-optimization

Dev leiden optimization

Author: ianfd

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "single-clustering"
-version = "0.6.0"
+version = "0.6.1"
 edition = "2024"
 authors = ["Ian F. Diks"]
 homepage = "https://singlerust.com"
@@ -12,13 +12,13 @@ description = "A high-performance network clustering library implementing commun
 
 [dependencies]
 anyhow = "1.0.98"
-kiddo = {version = "5.0.3" }
+kiddo = {version = "5.2.2" }
 nalgebra-sparse = "0.10.0"
 ndarray = {version = "0.16.1" , features = ["rayon"]}
 num-traits = "0.2.19"
-petgraph = { version = "0.8.1", features = ["rayon"] }
+petgraph = { version = "0.8.2", features = ["rayon"] }
 rayon = "1.10.0"
-single-utilities = "0.6.0"
+single-utilities = "0.8.5"
 rand = "0.9.0"
 rand_chacha = {version = "0.9.0"}
 hnsw_rs = {version = "0.3.2", features = ["simdeez_f"]}

Cargo.toml

@@ -1,38 +1,50 @@
 # single-clustering
 
-A Rust library for community detection and graph clustering algorithms.
+⚠️ **Development Status**: This library is currently under heavy development and should **not be considered production ready**. APIs may change significantly between versions.
+
+A Rust library for community detection and graph clustering algorithms with a focus on performance and flexibility.
 
 ## Features
 
-- **Network Analysis**: Efficient graph representation and manipulation for clustering tasks
-- **Community Detection**: Implementation of state-of-the-art algorithms
-    - Louvain method for community detection
-    - Leiden algorithm (enhanced version of Louvain)
-- **Flexible Grouping**: Abstract trait system for creating and managing node clusters
-- **Performance**: Parallel computation support via Rayon
-- **K-NN Graph Creation**: Build networks from high-dimensional data points
+- **Efficient Network Representation**: CSR (Compressed Sparse Row) format for optimal memory usage and performance
+- **Community Detection Algorithms**:
+    - **Leiden Algorithm**: State-of-the-art method with guaranteed well-connected communities
+    - **Louvain Method**: Classic modularity optimization (work-in-progress)
+- **Quality Functions**: Multiple partition quality metrics
+    - Modularity optimization
+    - Reichardt-Bornholdt (RB) configuration model with tunable resolution
+- **Flexible Architecture**: Generic trait-based design supporting different network types and grouping strategies
+- **Performance Optimized**: Caching strategies and efficient data structures for large networks
 
 ## Usage
 
 ```rust
-use single_clustering::network::Network;
-use single_clustering::network::grouping::VectorGrouping;
-use single_clustering::community_search::leiden::Leiden;
-
-// Create a network from your data
-let network = Network::new_from_graph(graph);
-
-// Initialize clustering (each node in its own cluster)
-let mut clustering = VectorGrouping::create_isolated(network.nodes());
-
-// Run Leiden algorithm (resolution parameter, randomness parameter, optional seed)
-let mut leiden = Leiden::new(1.0, 0.01, Some(42));
-leiden.iterate(&network, &mut clustering);
-
-// Access clustering results
-for node in 0..network.nodes() {
-    println!("Node {} belongs to cluster {}", node, clustering.get_group(node));
+use single_clustering::network::CSRNetwork;
+use single_clustering::community_search::leiden::{LeidenOptimizer, LeidenConfig};
+use single_clustering::community_search::leiden::partition::ModularityPartition;
+
+// Create a CSR network from your data
+let network = CSRNetwork::new(edges, weights, node_count);
+
+// Configure the Leiden algorithm
+let config = LeidenConfig {
+    max_iterations: 100,
+    tolerance: 1e-6,
+    seed: Some(42),
+    ..Default::default()
+};
+
+// Initialize the optimizer
+let mut optimizer = LeidenOptimizer::new(config);
+
+// Find communities using modularity optimization
+let partition: ModularityPartition<f64, _> = optimizer.find_partition(network)?;
+
+// Access results
+for node in 0..partition.node_count() {
+    println!("Node {} is in community {}", node, partition.membership(node));
 }
+println!("Modularity: {:.4}", partition.quality());
 ```
 
 ## Installation
@@ -41,16 +53,23 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-single-clustering = "0.1.0"
+single-clustering = "0.6.0"
 ```
 
-## Performance Considerations
+## Current Status
+
+- ✅ **Leiden Algorithm**: Core implementation with modularity and RB quality functions
+- ✅ **CSR Network Representation**: Efficient storage for large graphs
+- ✅ **Quality Functions**: Modularity and Reichardt-Bornholdt implementations
+- 🚧 **Louvain Algorithm**: Basic implementation (work-in-progress)
+- 🚧 **Documentation**: API documentation and examples (ongoing)
+- ❌ **Benchmarks**: Performance testing suite (planned)
+- ❌ **Python Bindings**: PyO3 integration (planned)
+
+## Contributing
 
-The library offers multiple implementations optimized for different scenarios:
-- `StandardLocalMoving`: Basic implementation of the moving algorithm
-- `FastLocalMoving`: Optimized version with better memory usage
-- Parallel implementations of various operations for large networks
+This project is in active development. Contributions, bug reports, and feature requests are welcome!
 
 ## License
 
-This crate is licensed under the MIT License.
+This crate is licensed under the BSD 3-Clause License.

README.md

@@ -1,39 +1,60 @@
-use std::collections::{HashSet, VecDeque};
+//! Leiden algorithm implementation for community detection in networks.
+//!
+//! The Leiden algorithm is an improvement over the Louvain algorithm that guarantees
+//! well-connected communities. It uses a refinement phase to ensure high-quality
+//! partitions by preventing poorly connected communities. IMPORTANT: This code is currently work-in-progress and neither production ready nor optimize to the fullest!
 
-use rand::{Rng, SeedableRng, seq::SliceRandom};
-use rand_chacha::ChaCha8Rng;
-use single_utilities::traits::FloatOpsTS;
-
-use crate::network::{Network, grouping::NetworkGrouping};
 pub mod partition;
 mod optimizer;
 pub use optimizer::LeidenOptimizer;
 
+/// Strategy for selecting communities to consider during optimization.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum ConsiderComms {
+    /// Consider all non-empty communities.
     AllComms = 1,
+    /// Consider communities of neighboring nodes only.
     AllNeighComms = 2,
+    /// Randomly select one community.
     RandComm = 3,
+    /// Randomly select a neighbor's community.
     RandNeighComm = 4,
 }
 
+/// Optimization routine for node movement during community detection.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum OptimiseRoutine {
+    /// Move individual nodes to different communities.
     MoveNodes = 10,
+    /// Merge entire nodes/communities together.
     MergeNodes = 11,
 }
 
+/// Configuration parameters for the Leiden algorithm.
+///
+/// Controls the behavior of community detection including iteration limits,
+/// convergence criteria, randomization, and optimization strategies.
 #[derive(Debug, Clone)]
 pub struct LeidenConfig {
+    /// Maximum number of iterations before termination.
     pub max_iterations: usize,
+    /// Convergence tolerance for quality improvement.
     pub tolerance: f64,
+    /// Random seed for reproducible results. None for random seed.
     pub seed: Option<u64>,
+    /// Maximum allowed community size. None for unlimited.
     pub max_community_size: Option<usize>,
+    /// Whether to perform partition refinement for better connectivity.
     pub refine_partition: bool,
+    /// Whether to consider moving nodes to empty communities.
     pub consider_empty_community: bool,
+    /// Strategy for selecting communities during main optimization.
     pub consider_comms: ConsiderComms,
+    /// Strategy for selecting communities during refinement.
     pub refine_consider_comms: ConsiderComms,
+    /// Optimization routine for main phase.
     pub optimise_routine: OptimiseRoutine,
+    /// Optimization routine for refinement phase.
     pub refine_routine: OptimiseRoutine,
 }