ruvector_sparsifier/
lib.rs

1//! # ruvector-sparsifier
2//!
3//! Dynamic spectral graph sparsification for the RuVector ecosystem.
4//!
5//! This crate maintains a small weighted shadow graph **H** (the *sparsifier*)
6//! that preserves the Laplacian energy of a full graph **G** within a factor
7//! of `(1 +/- epsilon)`. It follows the ADKKP16 approach adapted for
8//! practical real-time use:
9//!
10//! 1. **Backbone**: a spanning forest guaranteeing global connectivity.
11//! 2. **Importance scoring**: random-walk-based effective-resistance estimation.
12//! 3. **Spectral sampling**: edges kept proportional to `w * R_eff * log(n) / eps^2`.
13//! 4. **Periodic audits**: random quadratic-form probes detect drift.
14//!
15//! ## Quick start
16//!
17//! ```rust
18//! use ruvector_sparsifier::{AdaptiveGeoSpar, SparseGraph, SparsifierConfig, Sparsifier};
19//!
20//! // Build a graph.
21//! let g = SparseGraph::from_edges(&[
22//!     (0, 1, 1.0), (1, 2, 1.0), (2, 3, 1.0),
23//!     (3, 0, 1.0), (0, 2, 0.5),
24//! ]);
25//!
26//! // Construct the sparsifier.
27//! let mut spar = AdaptiveGeoSpar::build(&g, SparsifierConfig::default()).unwrap();
28//!
29//! // Dynamic updates.
30//! spar.insert_edge(1, 3, 2.0).unwrap();
31//! spar.delete_edge(0, 2).unwrap();
32//!
33//! // Audit quality.
34//! let audit = spar.audit();
35//! println!("Audit passed: {}, max error: {:.4}", audit.passed, audit.max_error);
36//!
37//! // Access the compressed graph.
38//! let h = spar.sparsifier();
39//! println!("Compression: {:.1}x ({} -> {} edges)",
40//!     spar.compression_ratio(),
41//!     spar.stats().full_edge_count,
42//!     h.num_edges(),
43//! );
44//! ```
45//!
46//! ## Feature flags
47//!
48//! | Flag              | Default | Description                              |
49//! |--------------------|---------|------------------------------------------|
50//! | `static-sparsify` | yes     | One-shot static sparsification           |
51//! | `dynamic`         | yes     | Dynamic insert/delete support            |
52//! | `simd`            | no      | SIMD-accelerated distance operations     |
53//! | `wasm`            | no      | WebAssembly-compatible paths             |
54//! | `audit`           | no      | Extended audit & diagnostics             |
55//! | `full`            | no      | All features                             |
56
57#![warn(missing_docs)]
58#![warn(clippy::all)]
59#![allow(clippy::module_name_repetitions)]
60#![allow(clippy::missing_errors_doc)]
61#![allow(clippy::missing_panics_doc)]
62
63pub mod audit;
64pub mod backbone;
65pub mod error;
66pub mod graph;
67pub mod importance;
68pub mod sampler;
69pub mod sparsifier;
70pub mod traits;
71pub mod types;
72
73// ---------------------------------------------------------------------------
74// Re-exports
75// ---------------------------------------------------------------------------
76
77pub use audit::SpectralAuditor;
78pub use backbone::Backbone;
79pub use error::{Result, SparsifierError};
80pub use graph::SparseGraph;
81pub use importance::{EffectiveResistanceEstimator, LocalImportanceScorer};
82pub use sampler::SpectralSampler;
83pub use sparsifier::AdaptiveGeoSpar;
84pub use traits::{BackboneStrategy, ImportanceScorer, Sparsifier};
85pub use types::{AuditResult, EdgeImportance, SparsifierConfig, SparsifierStats};
86
87/// Crate version.
88pub const VERSION: &str = env!("CARGO_PKG_VERSION");
89
90/// Crate name.
91pub const NAME: &str = env!("CARGO_PKG_NAME");
92
93/// Prelude for convenient imports.
94///
95/// Re-exports of the most commonly used types and traits.
96pub mod prelude {
97    pub use crate::{
98        AdaptiveGeoSpar, AuditResult, Backbone, BackboneStrategy, EdgeImportance,
99        EffectiveResistanceEstimator, ImportanceScorer, LocalImportanceScorer, SparseGraph,
100        Sparsifier, SparsifierConfig, SparsifierError, SparsifierStats, SpectralAuditor,
101        SpectralSampler,
102    };
103}
ruvector_sparsifier/lib.rs

ruvector_sparsifier/
lib.rs
