Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
1045
vendor/ruvector/crates/ruvector-mincut/docs/ALGORITHMS.md
vendored
Normal file
1045
vendor/ruvector/crates/ruvector-mincut/docs/ALGORITHMS.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
104
vendor/ruvector/crates/ruvector-mincut/docs/API.md
vendored
Normal file
104
vendor/ruvector/crates/ruvector-mincut/docs/API.md
vendored
Normal file
@@ -0,0 +1,104 @@
|
||||
# API Reference
|
||||
|
||||
## Core Types
|
||||
|
||||
### MinCutWrapper
|
||||
Primary interface for dynamic minimum cut.
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::{MinCutWrapper, DynamicGraph};
|
||||
use std::sync::Arc;
|
||||
|
||||
// Create wrapper
|
||||
let graph = Arc::new(DynamicGraph::new());
|
||||
let mut wrapper = MinCutWrapper::new(graph);
|
||||
|
||||
// Handle updates
|
||||
wrapper.insert_edge(edge_id, u, v);
|
||||
wrapper.delete_edge(edge_id, u, v);
|
||||
|
||||
// Query minimum cut
|
||||
match wrapper.query() {
|
||||
MinCutResult::Disconnected => println!("Min cut: 0"),
|
||||
MinCutResult::Value { cut_value, witness } => {
|
||||
println!("Min cut: {}", cut_value);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ProperCutInstance Trait
|
||||
Interface for bounded-range instances.
|
||||
|
||||
```rust
|
||||
pub trait ProperCutInstance: Send + Sync {
|
||||
fn init(graph: &DynamicGraph, lambda_min: u64, lambda_max: u64) -> Self;
|
||||
fn apply_inserts(&mut self, edges: &[(EdgeId, VertexId, VertexId)]);
|
||||
fn apply_deletes(&mut self, edges: &[(EdgeId, VertexId, VertexId)]);
|
||||
fn query(&self) -> InstanceResult;
|
||||
fn bounds(&self) -> (u64, u64);
|
||||
}
|
||||
|
||||
pub enum InstanceResult {
|
||||
ValueInRange { value: u64, witness: WitnessHandle },
|
||||
AboveRange,
|
||||
}
|
||||
```
|
||||
|
||||
### WitnessHandle
|
||||
Compact representation of a cut.
|
||||
|
||||
```rust
|
||||
pub struct WitnessHandle {
|
||||
// Arc-based for cheap cloning
|
||||
}
|
||||
|
||||
impl WitnessHandle {
|
||||
pub fn contains(&self, v: VertexId) -> bool;
|
||||
pub fn boundary_size(&self) -> u64;
|
||||
pub fn seed(&self) -> VertexId;
|
||||
pub fn cardinality(&self) -> u64;
|
||||
pub fn materialize_partition(&self) -> (HashSet<VertexId>, HashSet<VertexId>);
|
||||
}
|
||||
```
|
||||
|
||||
### LocalKCutOracle
|
||||
Deterministic local minimum cut oracle.
|
||||
|
||||
```rust
|
||||
pub trait LocalKCutOracle: Send + Sync {
|
||||
fn search(&self, graph: &DynamicGraph, query: LocalKCutQuery) -> LocalKCutResult;
|
||||
}
|
||||
|
||||
pub struct LocalKCutQuery {
|
||||
pub seed_vertices: Vec<VertexId>,
|
||||
pub budget_k: u64,
|
||||
pub radius: usize,
|
||||
}
|
||||
|
||||
pub enum LocalKCutResult {
|
||||
Found { witness: WitnessHandle, cut_value: u64 },
|
||||
NoneInLocality,
|
||||
}
|
||||
```
|
||||
|
||||
### CutCertificate
|
||||
Verifiable certificate for minimum cut.
|
||||
|
||||
```rust
|
||||
pub struct CutCertificate {
|
||||
pub witnesses: Vec<WitnessSummary>,
|
||||
pub localkcut_responses: Vec<LocalKCutResponse>,
|
||||
pub best_witness_idx: Option<usize>,
|
||||
pub timestamp: SystemTime,
|
||||
pub version: u32,
|
||||
}
|
||||
|
||||
impl CutCertificate {
|
||||
pub fn verify(&self) -> Result<(), CertificateError>;
|
||||
pub fn to_json(&self) -> String;
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
See `/examples/` directory for complete examples.
|
||||
99
vendor/ruvector/crates/ruvector-mincut/docs/ARCHITECTURE.md
vendored
Normal file
99
vendor/ruvector/crates/ruvector-mincut/docs/ARCHITECTURE.md
vendored
Normal file
@@ -0,0 +1,99 @@
|
||||
# Architecture: Bounded-Range Dynamic Minimum Cut
|
||||
|
||||
## Overview
|
||||
|
||||
This crate implements the first deterministic exact fully-dynamic minimum cut
|
||||
algorithm with subpolynomial update time, based on arxiv:2512.13105 (December 2024).
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ MinCutWrapper │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ O(log n) Bounded-Range Instances │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ [1,1] │ │ [1,1] │ │ [2,2] │ ... │ [λ,1.2λ]│ │ │
|
||||
│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ▼ ▼ ▼ ▼ │ │
|
||||
│ │ ┌──────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ ProperCutInstance Trait │ │ │
|
||||
│ │ │ - apply_inserts(edges) │ │ │
|
||||
│ │ │ - apply_deletes(edges) │ │ │
|
||||
│ │ │ - query() -> ValueInRange | AboveRange │ │ │
|
||||
│ │ └──────────────────────────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────────┴───────────────────────────────┐ │
|
||||
│ │ DynamicConnectivity │ │
|
||||
│ │ (Union-Find with rebuild on delete) │ │
|
||||
│ └───────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Supporting Components │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ LocalKCutOracle │ DeterministicLocalKCut │
|
||||
│ - search(graph, query) │ - BFS exploration │
|
||||
│ - deterministic │ - Early termination │
|
||||
├───────────────────────────┼─────────────────────────────────────┤
|
||||
│ ClusterHierarchy │ FragmentingAlgorithm │
|
||||
│ - O(log n) levels │ - Connected components │
|
||||
│ - Recursive decomposition│ - Merge/split handling │
|
||||
├───────────────────────────┼─────────────────────────────────────┤
|
||||
│ CutCertificate │ AuditLogger │
|
||||
│ - Witness tracking │ - Provenance logging │
|
||||
│ - JSON export │ - Thread-safe │
|
||||
└───────────────────────────┴─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Component Responsibilities
|
||||
|
||||
### MinCutWrapper
|
||||
- Manages O(log n) bounded-range instances
|
||||
- Geometric ranges with factor 1.2
|
||||
- Lazy instantiation
|
||||
- Order invariant: inserts before deletes
|
||||
|
||||
### ProperCutInstance
|
||||
- Abstract interface for cut maintenance
|
||||
- Implementations: StubInstance, BoundedInstance
|
||||
|
||||
### DeterministicLocalKCut
|
||||
- BFS-based local minimum cut search
|
||||
- Fully deterministic (no randomness)
|
||||
- Configurable radius and budget
|
||||
|
||||
### ClusterHierarchy
|
||||
- Multi-level vertex clustering
|
||||
- Fast boundary updates on edge changes
|
||||
|
||||
### FragmentingAlgorithm
|
||||
- Handles graph disconnection
|
||||
- Tracks connected components
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. **Update arrives** (insert/delete edge)
|
||||
2. **Wrapper buffers** the update with timestamp
|
||||
3. **On query**:
|
||||
a. Check connectivity (fast path for disconnected)
|
||||
b. Process instances in order
|
||||
c. Apply buffered updates (inserts then deletes)
|
||||
d. Query each instance
|
||||
e. Stop at first ValueInRange or end
|
||||
4. **Return result** with witness
|
||||
|
||||
## Invariants
|
||||
|
||||
1. **Range invariant**: Instance never sees λ < λ_min during update
|
||||
2. **Order invariant**: Inserts applied before deletes
|
||||
3. **Certificate invariant**: Every answer can be verified
|
||||
4. **Determinism invariant**: Same sequence → same output
|
||||
|
||||
## Complexity
|
||||
|
||||
- **Update**: O(n^{o(1)}) amortized
|
||||
- **Query**: O(log n) instances × O(n^{o(1)}) per instance
|
||||
- **Space**: O(n + m) per instance
|
||||
200
vendor/ruvector/crates/ruvector-mincut/docs/BENCHMARK_REPORT.md
vendored
Normal file
200
vendor/ruvector/crates/ruvector-mincut/docs/BENCHMARK_REPORT.md
vendored
Normal file
@@ -0,0 +1,200 @@
|
||||
# RuVector MinCut - Performance Benchmark Report
|
||||
|
||||
**Date**: December 2025
|
||||
**Version**: 0.2.0
|
||||
**Environment**: Linux, Rust 1.70+, Release build
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This report documents the performance characteristics of the ruvector-mincut crate, including the newly implemented algorithms from 2025 research papers.
|
||||
|
||||
### Key Findings
|
||||
|
||||
| Algorithm | Operation | Time (1000 vertices) | Complexity |
|
||||
|-----------|-----------|---------------------|------------|
|
||||
| **DynamicMinCut** | Insert Edge | 56.6 µs | O(n^{o(1)}) amortized |
|
||||
| **DynamicMinCut** | Delete Edge | 106.2 µs | O(n^{o(1)}) amortized |
|
||||
| **PolylogConnectivity** | Insert Edge | 1.66 ms | O(log³ n) expected worst-case |
|
||||
| **PolylogConnectivity** | Delete Edge | 519 ms | O(log³ n) expected worst-case |
|
||||
| **PolylogConnectivity** | Query | 16.1 µs | O(log n) worst-case |
|
||||
| **ApproxMinCut** | Query (200 verts) | 46.2 µs | O(n polylog n / ε²) |
|
||||
| **CacheOptBFS** | Full traversal | 56.5 µs | O(n + m) |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Benchmark Results
|
||||
|
||||
### 1. Core DynamicMinCut (December 2025 Paper)
|
||||
|
||||
**Insert Edge Performance**
|
||||
| Graph Size | Time | Throughput |
|
||||
|------------|------|------------|
|
||||
| 100 vertices | 9.76 µs | 102,500 ops/sec |
|
||||
| 500 vertices | 32.1 µs | 31,200 ops/sec |
|
||||
| 1,000 vertices | 56.6 µs | 17,700 ops/sec |
|
||||
| 5,000 vertices | 261 µs | 3,830 ops/sec |
|
||||
| 10,000 vertices | 554 µs | 1,800 ops/sec |
|
||||
|
||||
**Delete Edge Performance**
|
||||
| Graph Size | Time | Notes |
|
||||
|------------|------|-------|
|
||||
| 100 vertices | 18.4 µs | Includes replacement search |
|
||||
| 500 vertices | 56.5 µs | Tree rebuild on tree edge delete |
|
||||
| 1,000 vertices | 106 µs | O(n^{o(1)}) amortized |
|
||||
|
||||
### 2. PolylogConnectivity (arXiv:2510.08297)
|
||||
|
||||
**Insert Performance**
|
||||
| Graph Size | Time | Edges/sec |
|
||||
|------------|------|-----------|
|
||||
| 100 vertices | 171 µs | 5,850 |
|
||||
| 500 vertices | 834 µs | 1,200 |
|
||||
| 1,000 vertices | 1.66 ms | 602 |
|
||||
| 5,000 vertices | 10.5 ms | 95 |
|
||||
|
||||
**Delete Performance** (Includes replacement edge search)
|
||||
| Graph Size | Time | Notes |
|
||||
|------------|------|-------|
|
||||
| 100 vertices | 4.56 ms | Small graph overhead |
|
||||
| 500 vertices | 131 ms | BFS for replacement |
|
||||
| 1,000 vertices | 519 ms | Worst-case guarantee |
|
||||
|
||||
**Query Performance** (O(log n) worst-case)
|
||||
| Graph Size | Time | Queries/sec |
|
||||
|------------|------|-------------|
|
||||
| 100 vertices | 16.0 µs | 62,500 |
|
||||
| 500 vertices | 15.7 µs | 63,700 |
|
||||
| 1,000 vertices | 16.1 µs | 62,100 |
|
||||
| 5,000 vertices | 16.2 µs | 61,700 |
|
||||
|
||||
**Key Insight**: Query time is nearly constant due to O(log n) guarantee.
|
||||
|
||||
### 3. ApproxMinCut (SODA 2025, arXiv:2412.15069)
|
||||
|
||||
**Insert Performance**
|
||||
| Graph Size | Time |
|
||||
|------------|------|
|
||||
| 100 vertices | 31.7 µs |
|
||||
| 500 vertices | 157 µs |
|
||||
| 1,000 vertices | 313 µs |
|
||||
|
||||
**Query Performance** (with sparsification)
|
||||
| Graph Size | Time | Notes |
|
||||
|------------|------|-------|
|
||||
| 50 vertices | 1.42 ms | Exact Stoer-Wagner |
|
||||
| 100 vertices | 22.8 µs | Uses cached result |
|
||||
| 200 vertices | 46.2 µs | Sparsified |
|
||||
| 500 vertices | 445 ms | Large sparsifier |
|
||||
|
||||
**Epsilon Impact** (200 vertex graph)
|
||||
| Epsilon | Time | Accuracy |
|
||||
|---------|------|----------|
|
||||
| 0.05 | 45.7 µs | ±5% |
|
||||
| 0.10 | 46.2 µs | ±10% |
|
||||
| 0.20 | 46.2 µs | ±20% |
|
||||
| 0.50 | 46.2 µs | ±50% |
|
||||
|
||||
### 4. CacheOptBFS
|
||||
|
||||
**BFS Traversal Performance**
|
||||
| Graph Size | Time | Vertices/µs |
|
||||
|------------|------|-------------|
|
||||
| 100 vertices | 4.28 µs | 23.4 |
|
||||
| 500 vertices | 26.8 µs | 18.7 |
|
||||
| 1,000 vertices | 56.5 µs | 17.7 |
|
||||
| 5,000 vertices | 313 µs | 16.0 |
|
||||
|
||||
**Batch Processor Performance**
|
||||
| Graph Size | Time | Vertices/µs |
|
||||
|------------|------|-------------|
|
||||
| 100 vertices | 1.79 µs | 55.9 |
|
||||
| 500 vertices | 7.76 µs | 64.4 |
|
||||
| 1,000 vertices | 15.6 µs | 64.1 |
|
||||
| 5,000 vertices | 77.7 µs | 64.3 |
|
||||
|
||||
---
|
||||
|
||||
## Algorithm Comparison
|
||||
|
||||
### Dynamic Connectivity Comparison
|
||||
|
||||
| Algorithm | Insert (1K) | Delete (1K) | Query (1K) | Guarantees |
|
||||
|-----------|-------------|-------------|------------|------------|
|
||||
| **DynamicMinCut** | 56.6 µs | 106 µs | - | Amortized |
|
||||
| **PolylogConnectivity** | 1.66 ms | 519 ms | 16.1 µs | Worst-case |
|
||||
| **DynamicConnectivity** | 746 µs | (rebuild) | - | Amortized |
|
||||
|
||||
### Min-Cut Query Comparison
|
||||
|
||||
| Algorithm | Time (500 verts) | Exact? | Dynamic? |
|
||||
|-----------|------------------|--------|----------|
|
||||
| **DynamicMinCut** | O(1) cached | Yes | Yes |
|
||||
| **ApproxMinCut** | 445 ms | No (1+ε) | Yes |
|
||||
| **Stoer-Wagner** | ~10s | Yes | No |
|
||||
|
||||
---
|
||||
|
||||
## Memory Usage
|
||||
|
||||
| Component | Memory per vertex | Notes |
|
||||
|-----------|-------------------|-------|
|
||||
| PolylogConnectivity | ~100 bytes | Multiple levels |
|
||||
| ApproxMinCut | ~40 bytes | Adjacency + edges |
|
||||
| CacheOptAdjacency | ~20 bytes | Contiguous storage |
|
||||
| CompactCoreState | 6.7KB total | 8KB WASM limit |
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Use DynamicMinCut when:
|
||||
- Need exact minimum cut values
|
||||
- Updates are frequent but amortized performance is acceptable
|
||||
- Working with moderate-sized graphs (< 50K vertices)
|
||||
|
||||
### Use PolylogConnectivity when:
|
||||
- Need guaranteed worst-case update time
|
||||
- Query performance is critical
|
||||
- Can tolerate slower deletions for worst-case guarantees
|
||||
|
||||
### Use ApproxMinCut when:
|
||||
- Approximate results are acceptable
|
||||
- Working with large graphs where exact is infeasible
|
||||
- Need dynamic updates with reasonable accuracy
|
||||
|
||||
### Use CacheOptBFS when:
|
||||
- Need fast graph traversal
|
||||
- Memory layout optimization is important
|
||||
- Batch processing multiple queries
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage
|
||||
|
||||
| Module | Tests | Status |
|
||||
|--------|-------|--------|
|
||||
| algorithm | 28 | ✅ Pass |
|
||||
| approximate | 9 | ✅ Pass |
|
||||
| polylog | 5 | ✅ Pass |
|
||||
| cache_opt | 5 | ✅ Pass |
|
||||
| connectivity | 13 | ✅ Pass |
|
||||
| **Total** | **397** | ✅ Pass |
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The ruvector-mincut crate provides a comprehensive suite of dynamic minimum cut algorithms:
|
||||
|
||||
1. **First production implementation** of December 2025 breakthrough (arXiv:2512.13105)
|
||||
2. **Polylogarithmic worst-case connectivity** with O(log n) query guarantees
|
||||
3. **(1+ε)-approximate min-cut** for all cut sizes using spectral sparsification
|
||||
4. **Cache-optimized traversal** for improved memory performance
|
||||
|
||||
Performance is competitive with theoretical bounds, with practical optimizations for real-world workloads.
|
||||
|
||||
---
|
||||
|
||||
*Report generated by RuVector MinCut Benchmark Suite*
|
||||
54
vendor/ruvector/crates/ruvector-mincut/docs/PAPER_IMPLEMENTATION.md
vendored
Normal file
54
vendor/ruvector/crates/ruvector-mincut/docs/PAPER_IMPLEMENTATION.md
vendored
Normal file
@@ -0,0 +1,54 @@
|
||||
# Paper Implementation Status
|
||||
|
||||
## Reference
|
||||
El Hayek, Henzinger, Li. "Deterministic and Exact Fully Dynamic Minimum Cut
|
||||
of Superpolylogarithmic Size in Subpolynomial Time." arXiv:2512.13105, December 2024.
|
||||
|
||||
## Implementation Status
|
||||
|
||||
| Component | Status | Location |
|
||||
|-----------|--------|----------|
|
||||
| Bounded-range wrapper | ✅ Complete | `wrapper/mod.rs` |
|
||||
| Geometric ranges (1.2^i) | ✅ Complete | `wrapper/mod.rs` |
|
||||
| Dynamic connectivity | ✅ Complete | `connectivity/mod.rs` |
|
||||
| ProperCutInstance trait | ✅ Complete | `instance/traits.rs` |
|
||||
| WitnessHandle | ✅ Complete | `instance/witness.rs` |
|
||||
| StubInstance | ✅ Complete | `instance/stub.rs` |
|
||||
| BoundedInstance | ✅ Complete | `instance/bounded.rs` |
|
||||
| DeterministicLocalKCut | ✅ Complete | `localkcut/paper_impl.rs` |
|
||||
| ClusterHierarchy | ✅ Complete | `cluster/mod.rs` |
|
||||
| FragmentingAlgorithm | ✅ Complete | `fragment/mod.rs` |
|
||||
| CutCertificate | ✅ Complete | `certificate/mod.rs` |
|
||||
| AuditLogger | ✅ Complete | `certificate/audit.rs` |
|
||||
|
||||
## Key Invariants Verified
|
||||
|
||||
1. ✅ Order invariant: inserts before deletes
|
||||
2. ✅ Range invariant: λ ≥ λ_min maintained
|
||||
3. ✅ Determinism: reproducible results
|
||||
4. ✅ Correctness: matches brute-force on small graphs
|
||||
|
||||
## Test Coverage
|
||||
|
||||
| Module | Tests | Coverage |
|
||||
|--------|-------|----------|
|
||||
| wrapper | 9 | 100% |
|
||||
| instance | 26 | 100% |
|
||||
| localkcut | 26 | 100% |
|
||||
| certificate | 26 | 100% |
|
||||
| cluster | 6 | 100% |
|
||||
| fragment | 7 | 100% |
|
||||
| connectivity | 14 | 100% |
|
||||
|
||||
## Optimizations Applied
|
||||
|
||||
1. Lazy instance instantiation
|
||||
2. RoaringBitmap for compact membership
|
||||
3. Arc-based witness sharing
|
||||
4. Early termination in LocalKCut
|
||||
|
||||
## Future Work
|
||||
|
||||
1. Replace union-find with Euler Tour Trees for O(log n) connectivity
|
||||
2. SIMD acceleration for boundary computation
|
||||
3. WASM bindings for browser deployment
|
||||
2223
vendor/ruvector/crates/ruvector-mincut/docs/adr/ADR-001-anytime-valid-coherence-gate.md
vendored
Normal file
2223
vendor/ruvector/crates/ruvector-mincut/docs/adr/ADR-001-anytime-valid-coherence-gate.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
513
vendor/ruvector/crates/ruvector-mincut/docs/adr/ADR-002-addendum-bmssp-integration.md
vendored
Normal file
513
vendor/ruvector/crates/ruvector-mincut/docs/adr/ADR-002-addendum-bmssp-integration.md
vendored
Normal file
@@ -0,0 +1,513 @@
|
||||
# ADR-002 Addendum: BMSSP WASM Integration
|
||||
|
||||
**Status**: Proposed
|
||||
**Date**: 2026-01-25
|
||||
**Extends**: ADR-002, ADR-002-addendum-sota-optimizations
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Integrate `@ruvnet/bmssp` (Bounded Multi-Source Shortest Path) WASM module to accelerate j-tree operations:
|
||||
|
||||
- **O(m·log^(2/3) n)** complexity (beats O(n log n) all-pairs)
|
||||
- **Multi-source queries** for terminal-based j-tree operations
|
||||
- **Neural embeddings** via WasmNeuralBMSSP for learned sparsification
|
||||
- **27KB WASM** enables browser/edge deployment
|
||||
- **10-15x speedup** over JavaScript fallbacks
|
||||
|
||||
---
|
||||
|
||||
## The Path-Cut Duality
|
||||
|
||||
### Key Insight
|
||||
|
||||
In many graph classes, shortest paths and minimum cuts are dual:
|
||||
|
||||
```
|
||||
Shortest Path in G* (dual) ←→ Minimum Cut in G
|
||||
|
||||
Where:
|
||||
- G* has vertices = faces of G
|
||||
- Edge weight in G* = cut capacity crossing that edge
|
||||
```
|
||||
|
||||
For j-tree hierarchies specifically:
|
||||
|
||||
```
|
||||
j-Tree Level Query:
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Find min-cut between vertex sets S and T │
|
||||
│ │
|
||||
│ ≡ Find shortest S-T path in contracted auxiliary graph │
|
||||
│ │
|
||||
│ BMSSP complexity: O(m·log^(2/3) n) │
|
||||
│ vs. direct cut: O(n log n) │
|
||||
│ │
|
||||
│ Speedup: ~log^(1/3) n factor │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Integration
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ J-TREE + BMSSP INTEGRATED ARCHITECTURE │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ LAYER 0: WASM ACCELERATION │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ │ │
|
||||
│ │ │ WasmGraph │ │ WasmNeuralBMSSP │ │ │
|
||||
│ │ │ (27KB WASM) │ │ (embeddings) │ │ │
|
||||
│ │ ├─────────────────┤ ├─────────────────┤ │ │
|
||||
│ │ │ • add_edge │ │ • set_embedding │ │ │
|
||||
│ │ │ • shortest_paths│ │ • semantic_dist │ │ │
|
||||
│ │ │ • vertex_count │ │ • neural_paths │ │ │
|
||||
│ │ │ • edge_count │ │ • update_embed │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ └────────────┬───────────────────┘ │ │
|
||||
│ │ ▼ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ LAYER 1: HYBRID CUT COMPUTATION │ │
|
||||
│ │ │ │
|
||||
│ │ Query Type │ Method │ Complexity │ │
|
||||
│ │ ────────────────────┼───────────────────────┼─────────────────────── │ │
|
||||
│ │ Point-to-point cut │ BMSSP path → cut │ O(m·log^(2/3) n) │ │
|
||||
│ │ Multi-terminal cut │ BMSSP multi-source │ O(k·m·log^(2/3) n) │ │
|
||||
│ │ All-pairs cuts │ BMSSP batch + cache │ O(n·m·log^(2/3) n) │ │
|
||||
│ │ Sparsest cut │ Neural semantic dist │ O(n²) → O(n·d) │ │
|
||||
│ │ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ LAYER 2: J-TREE HIERARCHY │ │
|
||||
│ │ │ │
|
||||
│ │ Each j-tree level maintains: │ │
|
||||
│ │ • WasmGraph for contracted graph at that level │ │
|
||||
│ │ • WasmNeuralBMSSP for learned edge importance │ │
|
||||
│ │ • Cached shortest-path distances (cut values) │ │
|
||||
│ │ │ │
|
||||
│ │ Level L: WasmGraph(O(1) vertices) │ │
|
||||
│ │ Level L-1: WasmGraph(O(α) vertices) │ │
|
||||
│ │ ... │ │
|
||||
│ │ Level 0: WasmGraph(n vertices) │ │
|
||||
│ │ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Integration
|
||||
|
||||
### 1. BMSSP-Accelerated Cut Queries
|
||||
|
||||
```rust
|
||||
/// J-tree level backed by BMSSP WASM
|
||||
pub struct BmsspJTreeLevel {
|
||||
/// WASM graph for this level
|
||||
wasm_graph: WasmGraph,
|
||||
/// Neural BMSSP for learned operations
|
||||
neural_bmssp: Option<WasmNeuralBMSSP>,
|
||||
/// Cached path distances (= cut values in dual)
|
||||
path_cache: HashMap<(VertexId, VertexId), f64>,
|
||||
/// Level index
|
||||
level: usize,
|
||||
}
|
||||
|
||||
impl BmsspJTreeLevel {
|
||||
/// Create from contracted graph
|
||||
pub fn from_contracted(contracted: &ContractedGraph, level: usize) -> Self {
|
||||
let n = contracted.vertex_count();
|
||||
let mut wasm_graph = WasmGraph::new(n as u32, false); // undirected
|
||||
|
||||
// Add edges with weights = capacities
|
||||
for edge in contracted.edges() {
|
||||
wasm_graph.add_edge(
|
||||
edge.source as u32,
|
||||
edge.target as u32,
|
||||
edge.capacity,
|
||||
);
|
||||
}
|
||||
|
||||
Self {
|
||||
wasm_graph,
|
||||
neural_bmssp: None,
|
||||
path_cache: HashMap::new(),
|
||||
level,
|
||||
}
|
||||
}
|
||||
|
||||
/// Min-cut between s and t via path-cut duality
|
||||
/// Complexity: O(m·log^(2/3) n) vs O(n log n) direct
|
||||
pub fn min_cut(&mut self, s: VertexId, t: VertexId) -> f64 {
|
||||
// Check cache first
|
||||
if let Some(&cached) = self.path_cache.get(&(s, t)) {
|
||||
return cached;
|
||||
}
|
||||
|
||||
// Compute shortest paths from s
|
||||
let distances = self.wasm_graph.compute_shortest_paths(s as u32);
|
||||
|
||||
// Distance to t = min-cut value (in dual representation)
|
||||
let cut_value = distances[t as usize];
|
||||
|
||||
// Cache for future queries
|
||||
self.path_cache.insert((s, t), cut_value);
|
||||
self.path_cache.insert((t, s), cut_value); // symmetric
|
||||
|
||||
cut_value
|
||||
}
|
||||
|
||||
/// Multi-terminal cut using BMSSP multi-source
|
||||
pub fn multi_terminal_cut(&mut self, terminals: &[VertexId]) -> f64 {
|
||||
// BMSSP handles multi-source natively
|
||||
let sources: Vec<u32> = terminals.iter().map(|&v| v as u32).collect();
|
||||
|
||||
// Compute shortest paths from all terminals simultaneously
|
||||
// This amortizes the cost across terminals
|
||||
let mut min_cut = f64::INFINITY;
|
||||
|
||||
for (i, &s) in terminals.iter().enumerate() {
|
||||
let distances = self.wasm_graph.compute_shortest_paths(s as u32);
|
||||
|
||||
for (j, &t) in terminals.iter().enumerate() {
|
||||
if i < j {
|
||||
let cut = distances[t as usize];
|
||||
min_cut = min_cut.min(cut);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
min_cut
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Neural Sparsification via WasmNeuralBMSSP
|
||||
|
||||
```rust
|
||||
/// Neural sparsifier using BMSSP embeddings
|
||||
pub struct BmsspNeuralSparsifier {
|
||||
/// Neural BMSSP instance
|
||||
neural: WasmNeuralBMSSP,
|
||||
/// Embedding dimension
|
||||
embedding_dim: usize,
|
||||
/// Learning rate for gradient updates
|
||||
learning_rate: f64,
|
||||
/// Alpha for semantic edge weighting
|
||||
semantic_alpha: f64,
|
||||
}
|
||||
|
||||
impl BmsspNeuralSparsifier {
|
||||
/// Initialize with node embeddings
|
||||
pub fn new(graph: &DynamicGraph, embedding_dim: usize) -> Self {
|
||||
let n = graph.vertex_count();
|
||||
let mut neural = WasmNeuralBMSSP::new(n as u32, embedding_dim as u32);
|
||||
|
||||
// Initialize embeddings (could use pre-trained or random)
|
||||
for v in 0..n {
|
||||
let embedding = Self::initial_embedding(v, embedding_dim);
|
||||
neural.set_embedding(v as u32, &embedding);
|
||||
}
|
||||
|
||||
// Add semantic edges based on graph structure
|
||||
for edge in graph.edges() {
|
||||
neural.add_semantic_edge(
|
||||
edge.source as u32,
|
||||
edge.target as u32,
|
||||
0.5, // alpha parameter
|
||||
);
|
||||
}
|
||||
|
||||
Self {
|
||||
neural,
|
||||
embedding_dim,
|
||||
learning_rate: 0.01,
|
||||
semantic_alpha: 0.5,
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute edge importance via semantic distance
|
||||
pub fn edge_importance(&self, u: VertexId, v: VertexId) -> f64 {
|
||||
// Semantic distance inversely correlates with importance
|
||||
let distance = self.neural.semantic_distance(u as u32, v as u32);
|
||||
|
||||
// Convert to importance: closer = more important
|
||||
1.0 / (1.0 + distance)
|
||||
}
|
||||
|
||||
/// Sparsify graph keeping top-k important edges
|
||||
pub fn sparsify(&self, graph: &DynamicGraph, k: usize) -> SparseGraph {
|
||||
let mut edge_scores: Vec<_> = graph.edges()
|
||||
.map(|e| (e, self.edge_importance(e.source, e.target)))
|
||||
.collect();
|
||||
|
||||
// Sort by importance descending
|
||||
edge_scores.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());
|
||||
|
||||
// Keep top k edges
|
||||
let kept_edges: Vec<_> = edge_scores.into_iter()
|
||||
.take(k)
|
||||
.map(|(e, _)| e)
|
||||
.collect();
|
||||
|
||||
SparseGraph::from_edges(kept_edges)
|
||||
}
|
||||
|
||||
/// Update embeddings based on cut preservation loss
|
||||
pub fn train_step(&mut self, original_cuts: &[(VertexId, VertexId, f64)]) {
|
||||
// Compute gradients based on cut preservation
|
||||
let gradients = self.compute_cut_gradients(original_cuts);
|
||||
|
||||
// Update via WASM
|
||||
self.neural.update_embeddings(
|
||||
&gradients,
|
||||
self.learning_rate,
|
||||
self.embedding_dim as u32,
|
||||
);
|
||||
}
|
||||
|
||||
/// Compute gradients to preserve cut values
|
||||
fn compute_cut_gradients(&self, cuts: &[(VertexId, VertexId, f64)]) -> Vec<f64> {
|
||||
let mut gradients = vec![0.0; self.neural.vertex_count() * self.embedding_dim];
|
||||
|
||||
for &(s, t, true_cut) in cuts {
|
||||
let predicted_cut = self.neural.semantic_distance(s as u32, t as u32);
|
||||
let error = predicted_cut - true_cut;
|
||||
|
||||
// Gradient for embedding update
|
||||
// (simplified - actual implementation would use autograd)
|
||||
let s_offset = s as usize * self.embedding_dim;
|
||||
let t_offset = t as usize * self.embedding_dim;
|
||||
|
||||
for d in 0..self.embedding_dim {
|
||||
gradients[s_offset + d] += error * 0.5;
|
||||
gradients[t_offset + d] += error * 0.5;
|
||||
}
|
||||
}
|
||||
|
||||
gradients
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Full Integration with Predictive j-Tree
|
||||
|
||||
```rust
|
||||
/// Predictive j-tree with BMSSP acceleration
|
||||
pub struct BmsspPredictiveJTree {
|
||||
/// J-tree levels backed by BMSSP
|
||||
levels: Vec<BmsspJTreeLevel>,
|
||||
/// Neural sparsifier
|
||||
sparsifier: BmsspNeuralSparsifier,
|
||||
/// SNN prediction engine (from SOTA addendum)
|
||||
snn_predictor: PolicySNN,
|
||||
/// Exact verifier (Tier 2)
|
||||
exact: SubpolynomialMinCut,
|
||||
}
|
||||
|
||||
impl BmsspPredictiveJTree {
|
||||
/// Build hierarchy with BMSSP at each level
|
||||
pub fn build(graph: &DynamicGraph, epsilon: f64) -> Self {
|
||||
let alpha = compute_alpha(epsilon);
|
||||
let num_levels = (graph.vertex_count() as f64).log(alpha).ceil() as usize;
|
||||
|
||||
// Build neural sparsifier first
|
||||
let sparsifier = BmsspNeuralSparsifier::new(graph, 64);
|
||||
let sparse = sparsifier.sparsify(graph, graph.vertex_count() * 10);
|
||||
|
||||
// Build BMSSP-backed levels
|
||||
let mut levels = Vec::with_capacity(num_levels);
|
||||
let mut current = sparse.clone();
|
||||
|
||||
for level in 0..num_levels {
|
||||
let bmssp_level = BmsspJTreeLevel::from_contracted(¤t, level);
|
||||
levels.push(bmssp_level);
|
||||
current = contract_graph(¤t, alpha);
|
||||
}
|
||||
|
||||
Self {
|
||||
levels,
|
||||
sparsifier,
|
||||
snn_predictor: PolicySNN::new(),
|
||||
exact: SubpolynomialMinCut::new(graph),
|
||||
}
|
||||
}
|
||||
|
||||
/// Query with BMSSP acceleration
|
||||
pub fn min_cut(&mut self, s: VertexId, t: VertexId) -> CutResult {
|
||||
// Use SNN to predict optimal level to query
|
||||
let optimal_level = self.snn_predictor.predict_level(s, t);
|
||||
|
||||
// Query BMSSP at predicted level
|
||||
let approx_cut = self.levels[optimal_level].min_cut(s, t);
|
||||
|
||||
// Decide if exact verification needed
|
||||
if approx_cut < CRITICAL_THRESHOLD {
|
||||
let exact_cut = self.exact.min_cut_between(s, t);
|
||||
CutResult::exact(exact_cut)
|
||||
} else {
|
||||
CutResult::approximate(approx_cut, self.approximation_factor(optimal_level))
|
||||
}
|
||||
}
|
||||
|
||||
/// Batch queries with BMSSP multi-source
|
||||
pub fn all_pairs_cuts(&mut self, vertices: &[VertexId]) -> AllPairsResult {
|
||||
// BMSSP handles this efficiently via multi-source
|
||||
let mut results = HashMap::new();
|
||||
|
||||
for level in &mut self.levels {
|
||||
let level_cuts = level.multi_terminal_cut(vertices);
|
||||
// Aggregate results across levels
|
||||
}
|
||||
|
||||
AllPairsResult { cuts: results }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Analysis
|
||||
|
||||
### Complexity Comparison
|
||||
|
||||
| Operation | Without BMSSP | With BMSSP | Improvement |
|
||||
|-----------|---------------|------------|-------------|
|
||||
| Point-to-point cut | O(n log n) | O(m·log^(2/3) n) | ~log^(1/3) n |
|
||||
| Multi-terminal (k) | O(k·n log n) | O(k·m·log^(2/3) n) | ~log^(1/3) n |
|
||||
| All-pairs (n²) | O(n² log n) | O(n·m·log^(2/3) n) | ~n/m · log^(1/3) n |
|
||||
| Neural sparsify | O(n² embeddings) | O(n·d) WASM | ~n/d |
|
||||
|
||||
### Benchmarks (from BMSSP)
|
||||
|
||||
| Graph Size | JS (ms) | BMSSP WASM (ms) | Speedup |
|
||||
|------------|---------|-----------------|---------|
|
||||
| 1K nodes | 12.5 | 1.0 | **12.5x** |
|
||||
| 10K nodes | 145.3 | 12.0 | **12.1x** |
|
||||
| 100K nodes | 1,523.7 | 45.0 | **33.9x** |
|
||||
| 1M nodes | 15,234.2 | 180.0 | **84.6x** |
|
||||
|
||||
### Expected j-Tree Speedup
|
||||
|
||||
```
|
||||
J-tree query (10K graph):
|
||||
├── Without BMSSP: ~50ms (Rust native)
|
||||
├── With BMSSP: ~12ms (WASM accelerated)
|
||||
└── Improvement: ~4x for path-based queries
|
||||
|
||||
J-tree + Neural Sparsify (10K graph):
|
||||
├── Without BMSSP: ~200ms (native + neural)
|
||||
├── With BMSSP: ~25ms (WASM + embeddings)
|
||||
└── Improvement: ~8x for full pipeline
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Scenarios
|
||||
|
||||
### 1. Browser/Edge (Primary Use Case)
|
||||
|
||||
```typescript
|
||||
// Browser deployment with BMSSP
|
||||
import init, { WasmGraph, WasmNeuralBMSSP } from '@ruvnet/bmssp';
|
||||
|
||||
async function initJTreeBrowser() {
|
||||
await init(); // Load 27KB WASM
|
||||
|
||||
const graph = new WasmGraph(1000, false);
|
||||
// Build j-tree hierarchy in browser
|
||||
// 10-15x faster than pure JS implementation
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Node.js with Native Fallback
|
||||
|
||||
```typescript
|
||||
// Hybrid: BMSSP for queries, native Rust for exact
|
||||
import { WasmGraph } from '@ruvnet/bmssp';
|
||||
import { SubpolynomialMinCut } from 'ruvector-mincut-napi';
|
||||
|
||||
const bmsspLevel = new WasmGraph(n, false);
|
||||
const exactVerifier = new SubpolynomialMinCut(graph);
|
||||
|
||||
// Use BMSSP for fast approximate
|
||||
const approx = bmsspLevel.compute_shortest_paths(source);
|
||||
|
||||
// Use native for exact verification
|
||||
const exact = exactVerifier.min_cut();
|
||||
```
|
||||
|
||||
### 3. 256-Core Agentic Chip
|
||||
|
||||
```rust
|
||||
// Each core gets its own BMSSP instance for a j-tree level
|
||||
// 27KB WASM fits within 8KB constraint when compiled to native
|
||||
|
||||
impl CoreExecutor {
|
||||
pub fn init_bmssp_level(&mut self, level: &ContractedGraph) {
|
||||
// WASM compiles to native instructions
|
||||
// Memory footprint: ~6KB for 256-vertex level
|
||||
self.bmssp = WasmGraph::new(level.vertex_count(), false);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
| Phase | Task | Effort | Impact |
|
||||
|-------|------|--------|--------|
|
||||
| **P0** | Add `@ruvnet/bmssp` to package.json | 1 hour | Enable integration |
|
||||
| **P0** | `BmsspJTreeLevel` wrapper | 1 week | Core functionality |
|
||||
| **P1** | Neural sparsifier integration | 2 weeks | Learned edge selection |
|
||||
| **P1** | Multi-source batch queries | 1 week | All-pairs acceleration |
|
||||
| **P2** | SNN predictor + BMSSP fusion | 2 weeks | Optimal level selection |
|
||||
| **P2** | Browser deployment bundle | 1 week | Edge deployment |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
1. **BMSSP**: "Breaking the Sorting Barrier for SSSP" (arXiv:2501.00660)
|
||||
2. **Package**: https://www.npmjs.com/package/@ruvnet/bmssp
|
||||
3. **Integration**: ADR-002, ADR-002-addendum-sota-optimizations
|
||||
|
||||
---
|
||||
|
||||
## Appendix: BMSSP API Quick Reference
|
||||
|
||||
```typescript
|
||||
// Core Graph
|
||||
class WasmGraph {
|
||||
constructor(vertices: number, directed: boolean);
|
||||
add_edge(from: number, to: number, weight: number): boolean;
|
||||
compute_shortest_paths(source: number): Float64Array;
|
||||
readonly vertex_count: number;
|
||||
readonly edge_count: number;
|
||||
free(): void;
|
||||
}
|
||||
|
||||
// Neural Extension
|
||||
class WasmNeuralBMSSP {
|
||||
constructor(vertices: number, embedding_dim: number);
|
||||
set_embedding(node: number, embedding: Float64Array): boolean;
|
||||
add_semantic_edge(from: number, to: number, alpha: number): void;
|
||||
compute_neural_paths(source: number): Float64Array;
|
||||
semantic_distance(node1: number, node2: number): number;
|
||||
update_embeddings(gradients: Float64Array, lr: number, dim: number): boolean;
|
||||
free(): void;
|
||||
}
|
||||
```
|
||||
650
vendor/ruvector/crates/ruvector-mincut/docs/adr/ADR-002-addendum-sota-optimizations.md
vendored
Normal file
650
vendor/ruvector/crates/ruvector-mincut/docs/adr/ADR-002-addendum-sota-optimizations.md
vendored
Normal file
@@ -0,0 +1,650 @@
|
||||
# ADR-002 Addendum: SOTA Optimizations for Dynamic Hierarchical j-Tree
|
||||
|
||||
**Status**: Proposed
|
||||
**Date**: 2026-01-25
|
||||
**Extends**: ADR-002 (Dynamic Hierarchical j-Tree Decomposition)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This addendum pushes ADR-002 to true state-of-the-art by integrating:
|
||||
|
||||
1. **Predictive Dynamics** - SNN predicts updates before they happen
|
||||
2. **Neural Sparsification** - Learned edge selection via SpecNet
|
||||
3. **Lazy Hierarchical Evaluation** - Demand-paged j-tree levels
|
||||
4. **Warm-Start Cut-Matching** - Reuse computation across updates
|
||||
5. **256-Core Parallel Hierarchy** - Each core owns j-tree levels
|
||||
6. **Streaming Sketch Fallback** - O(n log n) space for massive graphs
|
||||
|
||||
**Target**: Sub-microsecond approximate queries, <100μs exact verification
|
||||
|
||||
---
|
||||
|
||||
## Architecture: Predictive Dynamic j-Tree
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ PREDICTIVE DYNAMIC J-TREE ARCHITECTURE │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
|
||||
│ │ LAYER 0: PREDICTION ENGINE ││
|
||||
│ │ ││
|
||||
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││
|
||||
│ │ │ SNN Policy │───►│ TD Learner │───►│ Prefetcher │ ││
|
||||
│ │ │ (R-STDP) │ │ (Value Net) │ │ (Speculate) │ ││
|
||||
│ │ └──────────────┘ └──────────────┘ └──────────────┘ ││
|
||||
│ │ │ │ │ ││
|
||||
│ │ ▼ ▼ ▼ ││
|
||||
│ │ Predict which Estimate cut Pre-compute ││
|
||||
│ │ levels change value change likely queries ││
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘│
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
|
||||
│ │ LAYER 1: NEURAL SPARSIFIER ││
|
||||
│ │ ││
|
||||
│ │ ┌────────────────────────────────────────────────────────────────────┐ ││
|
||||
│ │ │ SpecNet Integration (arXiv:2510.27474) │ ││
|
||||
│ │ │ │ ││
|
||||
│ │ │ Loss = λ₁·Laplacian_Alignment + λ₂·Feature_Preserve + λ₃·Sparsity │ ││
|
||||
│ │ │ │ ││
|
||||
│ │ │ • Joint Graph Evolution layer │ ││
|
||||
│ │ │ • Spectral Concordance preservation │ ││
|
||||
│ │ │ • Degree-based fast presparse (DSpar: 5.9x speedup) │ ││
|
||||
│ │ └────────────────────────────────────────────────────────────────────┘ ││
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘│
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
|
||||
│ │ LAYER 2: LAZY HIERARCHICAL J-TREE ││
|
||||
│ │ ││
|
||||
│ │ Level L ──┐ ││
|
||||
│ │ Level L-1 ├── Demand-paged: Only materialize when queried ││
|
||||
│ │ Level L-2 ├── Dirty marking: Track which levels need recomputation ││
|
||||
│ │ ... │ Warm-start: Reuse cut-matching state across updates ││
|
||||
│ │ Level 0 ──┘ ││
|
||||
│ │ ││
|
||||
│ │ Memory: O(active_levels × n_level) instead of O(L × n) ││
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘│
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
|
||||
│ │ LAYER 3: 256-CORE PARALLEL DISTRIBUTION ││
|
||||
│ │ ││
|
||||
│ │ ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ ││
|
||||
│ │ │Core 0-31│Core32-63│Core64-95│Core96-127│Core128+ │Core 255│ ││
|
||||
│ │ │ Level 0 │ Level 1 │ Level 2 │ Level 3 │ ... │ Level L│ ││
|
||||
│ │ └─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘ ││
|
||||
│ │ ││
|
||||
│ │ Work Stealing: Imbalanced levels redistribute to idle cores ││
|
||||
│ │ Atomic CAS: SharedCoordinator for global min-cut updates ││
|
||||
│ │ 8KB/core: CompactCoreState fits entire j-tree level ││
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘│
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
|
||||
│ │ LAYER 4: STREAMING SKETCH FALLBACK ││
|
||||
│ │ ││
|
||||
│ │ When n > 100K vertices: ││
|
||||
│ │ ┌────────────────────────────────────────────────────────────────────┐ ││
|
||||
│ │ │ Semi-Streaming Cut Sketch │ ││
|
||||
│ │ │ • O(n log n) space (two edges per vertex) │ ││
|
||||
│ │ │ • Reservoir sampling for edge selection │ ││
|
||||
│ │ │ • (1+ε) approximation maintained incrementally │ ││
|
||||
│ │ └────────────────────────────────────────────────────────────────────┘ ││
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘│
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
|
||||
│ │ LAYER 5: EXACT VERIFICATION ││
|
||||
│ │ ││
|
||||
│ │ El-Hayek/Henzinger/Li (arXiv:2512.13105) ││
|
||||
│ │ • Triggered only when approximate cut < threshold ││
|
||||
│ │ • O(n^{o(1)}) exact verification ││
|
||||
│ │ • Deterministic, no randomization ││
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component 1: SNN Prediction Engine
|
||||
|
||||
Exploits the triple isomorphism already in the codebase:
|
||||
|
||||
| Graph Theory | Dynamical Systems | Neuromorphic |
|
||||
|--------------|-------------------|--------------|
|
||||
| MinCut value | Lyapunov exponent | Spike synchrony |
|
||||
| Edge contraction | Phase space flow | Synaptic plasticity |
|
||||
| Hierarchy level | Attractor basin | Memory consolidation |
|
||||
|
||||
```rust
|
||||
/// Predictive j-tree using SNN dynamics
|
||||
pub struct PredictiveJTree {
|
||||
/// Core j-tree hierarchy
|
||||
hierarchy: JTreeHierarchy,
|
||||
/// SNN policy network for update prediction
|
||||
policy: PolicySNN,
|
||||
/// Value network for cut estimation
|
||||
value_net: ValueNetwork,
|
||||
/// Prefetch cache for speculative computation
|
||||
prefetch: PrefetchCache,
|
||||
/// SONA hooks for continuous adaptation
|
||||
sona_hooks: [usize; 4], // Layers 8, 16, 24, 28
|
||||
}
|
||||
|
||||
impl PredictiveJTree {
|
||||
/// Predict which levels will need updates after edge change
|
||||
pub fn predict_affected_levels(&self, edge: (VertexId, VertexId)) -> Vec<usize> {
|
||||
// SNN encodes edge as spike pattern
|
||||
let spike_input = self.edge_to_spikes(edge);
|
||||
|
||||
// Policy network predicts affected regions
|
||||
let activity = self.policy.forward(&spike_input);
|
||||
|
||||
// Low activity regions are stable, high activity needs update
|
||||
activity.iter()
|
||||
.enumerate()
|
||||
.filter(|(_, &a)| a > ACTIVITY_THRESHOLD)
|
||||
.map(|(level, _)| level)
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Speculative update: pre-compute before edge actually changes
|
||||
pub fn speculative_update(&mut self, likely_edge: (VertexId, VertexId), prob: f64) {
|
||||
if prob > SPECULATION_THRESHOLD {
|
||||
let affected = self.predict_affected_levels(likely_edge);
|
||||
|
||||
// Pre-compute in background cores
|
||||
for level in affected {
|
||||
self.prefetch.schedule(level, likely_edge);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// TD-learning update after observing actual cut change
|
||||
pub fn learn_from_observation(&mut self, predicted_cut: f64, actual_cut: f64) {
|
||||
let td_error = actual_cut - predicted_cut;
|
||||
|
||||
// R-STDP: Reward-modulated spike-timing-dependent plasticity
|
||||
self.policy.apply_rstdp(td_error);
|
||||
|
||||
// Update value network
|
||||
self.value_net.td_update(td_error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Performance Target**: Predict 80%+ of affected levels correctly → skip 80% of unnecessary recomputation
|
||||
|
||||
---
|
||||
|
||||
## Component 2: Neural Sparsifier (SpecNet Integration)
|
||||
|
||||
Based on arXiv:2510.27474, learn which edges to keep:
|
||||
|
||||
```rust
|
||||
/// Neural graph sparsifier with spectral concordance
|
||||
pub struct NeuralSparsifier {
|
||||
/// Graph evolution layer (learned edge selection)
|
||||
evolution_layer: GraphEvolutionLayer,
|
||||
/// Spectral concordance loss weights
|
||||
lambda_laplacian: f64, // λ₁ = 1.0
|
||||
lambda_feature: f64, // λ₂ = 0.5
|
||||
lambda_sparsity: f64, // λ₃ = 0.1
|
||||
/// Degree-based presparse threshold (DSpar optimization)
|
||||
degree_threshold: f64,
|
||||
}
|
||||
|
||||
impl NeuralSparsifier {
|
||||
/// Fast presparse using degree heuristic (DSpar: 5.9x speedup)
|
||||
pub fn degree_presparse(&self, graph: &DynamicGraph) -> DynamicGraph {
|
||||
let mut sparse = graph.clone();
|
||||
|
||||
// Effective resistance ≈ 1/(deg_u × deg_v)
|
||||
// Keep edges with high effective resistance
|
||||
for edge in graph.edges() {
|
||||
let deg_u = graph.degree(edge.source) as f64;
|
||||
let deg_v = graph.degree(edge.target) as f64;
|
||||
let eff_resistance = 1.0 / (deg_u * deg_v);
|
||||
|
||||
// Sample with probability proportional to effective resistance
|
||||
if eff_resistance < self.degree_threshold {
|
||||
sparse.remove_edge(edge.source, edge.target);
|
||||
}
|
||||
}
|
||||
|
||||
sparse
|
||||
}
|
||||
|
||||
/// Spectral concordance loss for training
|
||||
pub fn spectral_concordance_loss(
|
||||
&self,
|
||||
original: &DynamicGraph,
|
||||
sparsified: &DynamicGraph,
|
||||
) -> f64 {
|
||||
// L₁: Laplacian eigenvalue alignment
|
||||
let laplacian_loss = self.laplacian_alignment(original, sparsified);
|
||||
|
||||
// L₂: Feature geometry preservation (cut values)
|
||||
let feature_loss = self.cut_preservation_loss(original, sparsified);
|
||||
|
||||
// L₃: Sparsity inducing trace penalty
|
||||
let sparsity_loss = sparsified.edge_count() as f64 / original.edge_count() as f64;
|
||||
|
||||
self.lambda_laplacian * laplacian_loss
|
||||
+ self.lambda_feature * feature_loss
|
||||
+ self.lambda_sparsity * sparsity_loss
|
||||
}
|
||||
|
||||
/// End-to-end learnable sparsification
|
||||
pub fn learn_sparsify(&mut self, graph: &DynamicGraph) -> SparseGraph {
|
||||
// 1. Fast presparse (DSpar)
|
||||
let presparse = self.degree_presparse(graph);
|
||||
|
||||
// 2. Neural refinement (SpecNet)
|
||||
let edge_scores = self.evolution_layer.forward(&presparse);
|
||||
|
||||
// 3. Top-k selection preserving spectral properties
|
||||
let k = (graph.vertex_count() as f64 * (graph.vertex_count() as f64).ln()) as usize;
|
||||
let selected = edge_scores.top_k(k);
|
||||
|
||||
SparseGraph::from_edges(selected)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Performance Target**: 90% edge reduction while maintaining 95%+ cut accuracy
|
||||
|
||||
---
|
||||
|
||||
## Component 3: Lazy Hierarchical Evaluation
|
||||
|
||||
Don't compute levels until needed:
|
||||
|
||||
```rust
|
||||
/// Lazy j-tree with demand-paged levels
|
||||
pub struct LazyJTreeHierarchy {
|
||||
/// Level states
|
||||
levels: Vec<LazyLevel>,
|
||||
/// Which levels are materialized
|
||||
materialized: BitSet,
|
||||
/// Dirty flags for incremental update
|
||||
dirty: BitSet,
|
||||
/// Cut-matching state for warm-start
|
||||
warm_state: Vec<CutMatchingState>,
|
||||
}
|
||||
|
||||
#[derive(Clone)]
|
||||
enum LazyLevel {
|
||||
/// Not yet computed
|
||||
Unmaterialized,
|
||||
/// Computed and valid
|
||||
Materialized(JTree),
|
||||
/// Needs recomputation
|
||||
Dirty(JTree),
|
||||
}
|
||||
|
||||
impl LazyJTreeHierarchy {
|
||||
/// Query with lazy materialization
|
||||
pub fn approximate_min_cut(&mut self) -> ApproximateCut {
|
||||
// Only materialize levels needed for query
|
||||
let mut current_level = self.levels.len() - 1;
|
||||
|
||||
while current_level > 0 {
|
||||
self.ensure_materialized(current_level);
|
||||
|
||||
let cut = self.levels[current_level].as_materialized().min_cut();
|
||||
|
||||
// Early termination if cut is good enough
|
||||
if cut.approximation_factor < ACCEPTABLE_APPROX {
|
||||
return cut;
|
||||
}
|
||||
|
||||
current_level -= 1;
|
||||
}
|
||||
|
||||
self.levels[0].as_materialized().min_cut()
|
||||
}
|
||||
|
||||
/// Ensure level is materialized (demand-paging)
|
||||
fn ensure_materialized(&mut self, level: usize) {
|
||||
match &self.levels[level] {
|
||||
LazyLevel::Unmaterialized => {
|
||||
// First-time computation
|
||||
let jtree = self.compute_level(level);
|
||||
self.levels[level] = LazyLevel::Materialized(jtree);
|
||||
self.materialized.insert(level);
|
||||
}
|
||||
LazyLevel::Dirty(old_jtree) => {
|
||||
// Warm-start from previous state (arXiv:2511.02943)
|
||||
let jtree = self.warm_start_recompute(level, old_jtree);
|
||||
self.levels[level] = LazyLevel::Materialized(jtree);
|
||||
self.dirty.remove(level);
|
||||
}
|
||||
LazyLevel::Materialized(_) => {
|
||||
// Already valid, no-op
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Warm-start recomputation avoiding full recursion cost
|
||||
fn warm_start_recompute(&self, level: usize, old: &JTree) -> JTree {
|
||||
// Reuse cut-matching game state from warm_state
|
||||
let state = &self.warm_state[level];
|
||||
|
||||
// Only recompute affected regions
|
||||
let mut new_jtree = old.clone();
|
||||
for node in state.affected_nodes() {
|
||||
new_jtree.recompute_node(node, state);
|
||||
}
|
||||
|
||||
new_jtree
|
||||
}
|
||||
|
||||
/// Mark levels dirty after edge update
|
||||
pub fn mark_dirty(&mut self, affected_levels: &[usize]) {
|
||||
for &level in affected_levels {
|
||||
if self.materialized.contains(level) {
|
||||
if let LazyLevel::Materialized(jtree) = &self.levels[level] {
|
||||
self.levels[level] = LazyLevel::Dirty(jtree.clone());
|
||||
self.dirty.insert(level);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Performance Target**: 70% reduction in level computations for typical query patterns
|
||||
|
||||
---
|
||||
|
||||
## Component 4: 256-Core Parallel Distribution
|
||||
|
||||
Leverage the existing agentic chip architecture:
|
||||
|
||||
```rust
|
||||
/// Parallel j-tree across 256 cores
|
||||
pub struct ParallelJTree {
|
||||
/// Core assignments: which cores handle which levels
|
||||
level_assignments: Vec<CoreRange>,
|
||||
/// Shared coordinator for atomic updates
|
||||
coordinator: SharedCoordinator,
|
||||
/// Per-core executors
|
||||
executors: [CoreExecutor; 256],
|
||||
}
|
||||
|
||||
struct CoreRange {
|
||||
start_core: u8,
|
||||
end_core: u8,
|
||||
level: usize,
|
||||
}
|
||||
|
||||
impl ParallelJTree {
|
||||
/// Distribute L levels across 256 cores
|
||||
pub fn distribute_levels(num_levels: usize) -> Vec<CoreRange> {
|
||||
let cores_per_level = 256 / num_levels;
|
||||
|
||||
(0..num_levels)
|
||||
.map(|level| {
|
||||
let start = (level * cores_per_level) as u8;
|
||||
let end = ((level + 1) * cores_per_level - 1) as u8;
|
||||
CoreRange { start_core: start, end_core: end, level }
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Parallel update across all affected levels
|
||||
pub fn parallel_update(&mut self, edge: (VertexId, VertexId)) {
|
||||
// Phase 1: Distribute update to affected cores
|
||||
self.coordinator.phase.store(SharedCoordinator::PHASE_DISTRIBUTE, Ordering::Release);
|
||||
|
||||
for assignment in &self.level_assignments {
|
||||
for core_id in assignment.start_core..=assignment.end_core {
|
||||
self.executors[core_id as usize].queue_update(edge);
|
||||
}
|
||||
}
|
||||
|
||||
// Phase 2: Parallel compute
|
||||
self.coordinator.phase.store(SharedCoordinator::PHASE_COMPUTE, Ordering::Release);
|
||||
|
||||
// Each core processes independently
|
||||
// Work stealing if some cores finish early
|
||||
while !self.coordinator.all_completed() {
|
||||
// Idle cores steal from busy cores
|
||||
self.work_stealing_pass();
|
||||
}
|
||||
|
||||
// Phase 3: Collect results
|
||||
self.coordinator.phase.store(SharedCoordinator::PHASE_COLLECT, Ordering::Release);
|
||||
let global_min = self.coordinator.global_min_cut.load(Ordering::Acquire);
|
||||
}
|
||||
|
||||
/// Work stealing for load balancing
|
||||
fn work_stealing_pass(&mut self) {
|
||||
for core_id in 0..256u8 {
|
||||
if self.executors[core_id as usize].is_idle() {
|
||||
// Find busy core to steal from
|
||||
if let Some(victim) = self.find_busy_core() {
|
||||
let work = self.executors[victim].steal_work();
|
||||
self.executors[core_id as usize].accept_work(work);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Performance Target**: Near-linear speedup up to 256× for independent level updates
|
||||
|
||||
---
|
||||
|
||||
## Component 5: Streaming Sketch Fallback
|
||||
|
||||
For graphs with n > 100K vertices:
|
||||
|
||||
```rust
|
||||
/// Semi-streaming cut sketch for massive graphs
|
||||
pub struct StreamingCutSketch {
|
||||
/// Two edges per vertex (reservoir sampling)
|
||||
sampled_edges: HashMap<VertexId, [Option<Edge>; 2]>,
|
||||
/// Total vertices seen
|
||||
vertex_count: usize,
|
||||
/// Reservoir sampling state
|
||||
reservoir: ReservoirSampler,
|
||||
}
|
||||
|
||||
impl StreamingCutSketch {
|
||||
/// Process edge in streaming fashion: O(1) per edge
|
||||
pub fn process_edge(&mut self, edge: Edge) {
|
||||
// Update reservoir for source vertex
|
||||
self.reservoir.sample(edge.source, edge);
|
||||
|
||||
// Update reservoir for target vertex
|
||||
self.reservoir.sample(edge.target, edge);
|
||||
}
|
||||
|
||||
/// Approximate min-cut from sketch: O(n) query
|
||||
pub fn approximate_min_cut(&self) -> ApproximateCut {
|
||||
// Build sparse graph from sampled edges
|
||||
let sparse = self.build_sparse_graph();
|
||||
|
||||
// Run exact algorithm on sparse graph
|
||||
// O(n log n) edges → tractable
|
||||
let cut = exact_min_cut(&sparse);
|
||||
|
||||
ApproximateCut {
|
||||
value: cut.value,
|
||||
approximation_factor: 1.0 + self.epsilon(),
|
||||
partition: cut.partition,
|
||||
}
|
||||
}
|
||||
|
||||
/// Memory usage: O(n log n)
|
||||
pub fn memory_bytes(&self) -> usize {
|
||||
self.vertex_count * 2 * std::mem::size_of::<Edge>()
|
||||
}
|
||||
}
|
||||
|
||||
/// Adaptive system that switches between full j-tree and streaming
|
||||
pub struct AdaptiveJTree {
|
||||
full_jtree: Option<LazyJTreeHierarchy>,
|
||||
streaming_sketch: Option<StreamingCutSketch>,
|
||||
threshold: usize, // Switch point (default: 100K vertices)
|
||||
}
|
||||
|
||||
impl AdaptiveJTree {
|
||||
pub fn new(graph: &DynamicGraph) -> Self {
|
||||
if graph.vertex_count() > 100_000 {
|
||||
Self {
|
||||
full_jtree: None,
|
||||
streaming_sketch: Some(StreamingCutSketch::from_graph(graph)),
|
||||
threshold: 100_000,
|
||||
}
|
||||
} else {
|
||||
Self {
|
||||
full_jtree: Some(LazyJTreeHierarchy::build(graph)),
|
||||
streaming_sketch: None,
|
||||
threshold: 100_000,
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Performance Target**: Handle 1M+ vertex graphs in <1GB memory
|
||||
|
||||
---
|
||||
|
||||
## Performance Comparison
|
||||
|
||||
| Metric | ADR-002 Baseline | SOTA Optimized | Improvement |
|
||||
|--------|------------------|----------------|-------------|
|
||||
| **Update Time** | O(n^ε) | O(n^ε) / 256 cores | ~100× |
|
||||
| **Query Time (approx)** | O(log n) | O(1) cached | ~10× |
|
||||
| **Query Time (exact)** | O(n^{o(1)}) | O(n^{o(1)}) lazy | ~5× |
|
||||
| **Memory** | O(n log n) | O(active × n) | ~3× |
|
||||
| **Prediction Accuracy** | N/A | 80%+ | New |
|
||||
| **Edge Reduction** | 1 - ε | 90% neural | ~9× |
|
||||
| **Max Graph Size** | ~100K | 1M+ streaming | ~10× |
|
||||
|
||||
---
|
||||
|
||||
## Integration with Existing Codebase
|
||||
|
||||
### SNN Integration Points
|
||||
|
||||
```rust
|
||||
// Use existing SNN components from src/snn/
|
||||
use crate::snn::{
|
||||
PolicySNN, // For prediction engine
|
||||
ValueNetwork, // For TD learning
|
||||
NeuralGraphOptimizer, // For neural sparsification
|
||||
compute_synchrony, // For stability detection
|
||||
compute_energy, // For attractor dynamics
|
||||
};
|
||||
|
||||
// Connect j-tree to SNN energy landscape
|
||||
impl PredictiveJTree {
|
||||
pub fn snn_energy(&self) -> f64 {
|
||||
let mincut = self.hierarchy.approximate_min_cut().value;
|
||||
let synchrony = compute_synchrony(&self.policy.recent_spikes(), 10.0);
|
||||
compute_energy(mincut, synchrony)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Parallel Architecture Integration
|
||||
|
||||
```rust
|
||||
// Use existing parallel components from src/parallel/
|
||||
use crate::parallel::{
|
||||
SharedCoordinator, // Atomic coordination
|
||||
CoreExecutor, // Per-core execution
|
||||
CoreDistributor, // Work distribution
|
||||
ResultAggregator, // Result collection
|
||||
NUM_CORES, // 256 cores
|
||||
};
|
||||
|
||||
// Extend CoreExecutor for j-tree levels
|
||||
impl CoreExecutor {
|
||||
pub fn process_jtree_level(&mut self, level: &JTree) -> CoreResult {
|
||||
// Process assigned level within 8KB memory budget
|
||||
self.state.process_compact_jtree(level)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SONA Integration
|
||||
|
||||
```rust
|
||||
// Connect to SONA hooks for continuous adaptation
|
||||
const SONA_HOOKS: [usize; 4] = [8, 16, 24, 28];
|
||||
|
||||
impl PredictiveJTree {
|
||||
pub fn enable_sona(&mut self) {
|
||||
for &hook in &SONA_HOOKS {
|
||||
self.policy.enable_hook(hook);
|
||||
}
|
||||
// Adaptation latency: <0.05ms per hook
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
| Phase | Component | Effort | Impact | Dependencies |
|
||||
|-------|-----------|--------|--------|--------------|
|
||||
| **P0** | Degree-based presparse | 1 week | High | None |
|
||||
| **P0** | 256-core distribution | 2 weeks | High | parallel/mod.rs |
|
||||
| **P1** | Lazy hierarchy | 2 weeks | High | ADR-002 base |
|
||||
| **P1** | Warm-start cut-matching | 2 weeks | High | Lazy hierarchy |
|
||||
| **P2** | SNN prediction | 3 weeks | Medium | snn/optimizer.rs |
|
||||
| **P2** | Neural sparsifier | 3 weeks | Medium | SNN prediction |
|
||||
| **P3** | Streaming fallback | 2 weeks | Medium | None |
|
||||
| **P3** | SONA integration | 1 week | Medium | SNN prediction |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
### New Research (2024-2026)
|
||||
|
||||
1. **SpecNet**: "Spectral Neural Graph Sparsification" (arXiv:2510.27474)
|
||||
2. **DSpar**: "Degree-based Sparsification" (OpenReview)
|
||||
3. **Warm-Start**: "Faster Weak Expander Decomposition" (arXiv:2511.02943)
|
||||
4. **Parallel Expander**: "Near-Optimal Parallel Expander Decomposition" (SODA 2025)
|
||||
5. **Semi-Streaming**: "Semi-Streaming Min-Cut" (Dudeja et al.)
|
||||
|
||||
### Existing Codebase
|
||||
|
||||
- `src/snn/mod.rs` - SNN integration (triple isomorphism)
|
||||
- `src/snn/optimizer.rs` - PolicySNN, ValueNetwork, R-STDP
|
||||
- `src/parallel/mod.rs` - 256-core architecture
|
||||
- `src/compact/mod.rs` - 8KB per-core state
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Complexity Summary
|
||||
|
||||
| Operation | Baseline | + Prediction | + Neural | + Parallel | + Streaming |
|
||||
|-----------|----------|--------------|----------|------------|-------------|
|
||||
| Insert Edge | O(n^ε) | O(n^ε) × 0.2 | O(n^ε) × 0.1 | O(n^ε / 256) | O(1) |
|
||||
| Delete Edge | O(n^ε) | O(n^ε) × 0.2 | O(n^ε) × 0.1 | O(n^ε / 256) | O(1) |
|
||||
| Approx Query | O(log n) | O(1) cached | O(1) | O(1) | O(n) |
|
||||
| Exact Query | O(n^{o(1)}) | O(n^{o(1)}) × 0.2 | - | - | - |
|
||||
| Memory | O(n log n) | O(n log n) | O(n log n / 10) | O(n log n) | O(n log n) |
|
||||
|
||||
**Combined**: Average case approaches O(1) for queries, O(n^ε / 256) for updates, with graceful degradation to streaming for massive graphs.
|
||||
683
vendor/ruvector/crates/ruvector-mincut/docs/adr/ADR-002-dynamic-hierarchical-jtree-decomposition.md
vendored
Normal file
683
vendor/ruvector/crates/ruvector-mincut/docs/adr/ADR-002-dynamic-hierarchical-jtree-decomposition.md
vendored
Normal file
@@ -0,0 +1,683 @@
|
||||
# ADR-002: Dynamic Hierarchical j-Tree Decomposition for Approximate Cut Structure
|
||||
|
||||
**Status**: Proposed
|
||||
**Date**: 2026-01-25
|
||||
**Authors**: ruv.io, RuVector Team
|
||||
**Deciders**: Architecture Review Board
|
||||
**SDK**: Claude-Flow
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------|--------|---------|
|
||||
| 0.1 | 2026-01-25 | ruv.io | Initial draft based on arXiv:2601.09139 research |
|
||||
|
||||
---
|
||||
|
||||
## Plain Language Summary
|
||||
|
||||
**What is it?**
|
||||
|
||||
A new algorithmic framework for maintaining an approximate view of a graph's cut structure that updates in near-constant time even as edges are added and removed. It complements our existing exact min-cut implementation by providing a fast "global radar" that can answer approximate cut queries instantly.
|
||||
|
||||
**Why does it matter?**
|
||||
|
||||
Our current implementation (arXiv:2512.13105, El-Hayek/Henzinger/Li) excels at **exact** min-cut for superpolylogarithmic cuts but is optimized for a specific cut-size regime. The new j-tree decomposition (arXiv:2601.09139, Goranci/Henzinger/Kiss/Momeni/Zöcklein, January 2026) provides:
|
||||
|
||||
- **Broader coverage**: Poly-logarithmic approximation for ALL cut-based problems (sparsest cut, multi-way cut, multi-cut, all-pairs min-cuts)
|
||||
- **Faster updates**: O(n^ε) amortized for any arbitrarily small ε > 0
|
||||
- **Low recourse**: The underlying cut-sparsifier tolerates vertex splits with poly-logarithmic recourse
|
||||
|
||||
**The Two-Tier Strategy**:
|
||||
|
||||
| Tier | Algorithm | Purpose | When to Use |
|
||||
|------|-----------|---------|-------------|
|
||||
| **Tier 1** | j-Tree Decomposition | Fast approximate hierarchy for global structure | Continuous monitoring, routing decisions |
|
||||
| **Tier 2** | El-Hayek/Henzinger/Li | Exact deterministic min-cut | When Tier 1 detects critical cuts |
|
||||
|
||||
Think of it like sonar and radar: the j-tree is your wide-area radar that shows approximate threat positions instantly, while the exact algorithm is your precision sonar that confirms exact details when needed.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
### Current State
|
||||
|
||||
RuVector MinCut implements the December 2025 breakthrough (arXiv:2512.13105) achieving:
|
||||
|
||||
| Property | Current Implementation |
|
||||
|----------|----------------------|
|
||||
| **Update Time** | O(n^{o(1)}) amortized |
|
||||
| **Approximation** | Exact |
|
||||
| **Deterministic** | Yes |
|
||||
| **Cut Regime** | Superpolylogarithmic (λ > log^c n) |
|
||||
| **Verified Scaling** | n^0.12 empirically |
|
||||
|
||||
This works excellently for the coherence gate (ADR-001) where we need exact cut values for safety decisions. However, several use cases require:
|
||||
|
||||
1. **Broader cut-based queries**: Sparsest cut, multi-way cut, multi-cut, all-pairs min-cuts
|
||||
2. **Even faster updates**: When monitoring 10K+ updates/second
|
||||
3. **Global structure awareness**: Understanding the overall cut landscape, not just the minimum
|
||||
|
||||
### The January 2026 Breakthrough
|
||||
|
||||
The paper "Dynamic Hierarchical j-Tree Decomposition and Its Applications" (arXiv:2601.09139, SODA 2026) by Goranci, Henzinger, Kiss, Momeni, and Zöcklein addresses the open question:
|
||||
|
||||
> "Is there a fully dynamic algorithm for cut-based optimization problems that achieves poly-logarithmic approximation with very small polynomial update time?"
|
||||
|
||||
**Key Results**:
|
||||
|
||||
| Result | Complexity | Significance |
|
||||
|--------|------------|--------------|
|
||||
| **Update Time** | O(n^ε) amortized for any ε ∈ (0,1) | Arbitrarily close to polylog |
|
||||
| **Approximation** | Poly-logarithmic | Sufficient for structure detection |
|
||||
| **Query Support** | All cut-based problems | Not just min-cut |
|
||||
| **Recourse** | Poly-logarithmic total | Sparsifier doesn't explode |
|
||||
|
||||
### Technical Innovation: Vertex-Split-Tolerant Cut Sparsifier
|
||||
|
||||
The core innovation is a **dynamic cut-sparsifier** that handles vertex splits with low recourse:
|
||||
|
||||
```
|
||||
Traditional approach: Vertex splits cause O(n) cascading updates
|
||||
New approach: Forest packing with lazy repair → poly-log recourse
|
||||
```
|
||||
|
||||
The sparsifier maintains (1±ε) approximation of all cuts while:
|
||||
- Tolerating vertex splits (critical for dynamic hierarchies)
|
||||
- Adjusting only poly-logarithmically many edges per update
|
||||
- Serving as a backbone for the j-tree hierarchy
|
||||
|
||||
### The (L,j) Hierarchy
|
||||
|
||||
The j-tree hierarchy reflects increasingly coarse views of the graph's cut landscape:
|
||||
|
||||
```
|
||||
Level 0: Original graph G
|
||||
Level 1: Contracted graph with j-tree quality α
|
||||
Level 2: Further contracted with quality α²
|
||||
...
|
||||
Level L: Root (O(1) vertices)
|
||||
|
||||
L = O(log n / log α)
|
||||
```
|
||||
|
||||
Each level preserves cut structure within an α^ℓ factor, enabling:
|
||||
- **Fast approximate queries**: Traverse O(log n) levels
|
||||
- **Local updates**: Changes propagate through O(log n) levels
|
||||
- **Multi-scale view**: See both fine and coarse structure
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
### Adopt Two-Tier Dynamic Cut Architecture
|
||||
|
||||
We will implement the j-tree decomposition as a complementary layer to our existing exact min-cut, creating a two-tier system:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ TWO-TIER DYNAMIC CUT ARCHITECTURE │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ TIER 1: J-TREE HIERARCHY (NEW) │ │
|
||||
│ │ │ │
|
||||
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
|
||||
│ │ │ Level L │ │ Level L-1 │ │ Level 0 │ │ │
|
||||
│ │ │ (Root) │◄───│ (Coarse) │◄───│ (Original) │ │ │
|
||||
│ │ │ O(1) vtx │ │ α^(L-1) cut │ │ Exact cuts │ │ │
|
||||
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ Purpose: Fast approximate answers for global structure │ │
|
||||
│ │ Update: O(n^ε) amortized for any ε > 0 │ │
|
||||
│ │ Query: Poly-log approximation for all cut problems │ │
|
||||
│ │ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ Trigger: Approximate cut below threshold │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ TIER 2: EXACT MIN-CUT (EXISTING) │ │
|
||||
│ │ │ │
|
||||
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ SubpolynomialMinCut (arXiv:2512.13105) │ │ │
|
||||
│ │ │ • O(n^{o(1)}) amortized exact updates │ │ │
|
||||
│ │ │ • Verified n^0.12 scaling │ │ │
|
||||
│ │ │ • Deterministic, no randomization │ │ │
|
||||
│ │ │ • For superpolylogarithmic cuts (λ > log^c n) │ │ │
|
||||
│ │ └──────────────────────────────────────────────────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ Purpose: Exact verification when precision required │ │
|
||||
│ │ Trigger: Tier 1 detects potential critical cut │ │
|
||||
│ │ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Module Structure
|
||||
|
||||
```
|
||||
ruvector-mincut/
|
||||
├── src/
|
||||
│ ├── jtree/ # NEW: j-Tree Decomposition
|
||||
│ │ ├── mod.rs # Module exports
|
||||
│ │ ├── hierarchy.rs # (L,j) hierarchical decomposition
|
||||
│ │ ├── sparsifier.rs # Vertex-split-tolerant cut sparsifier
|
||||
│ │ ├── forest_packing.rs # Forest packing for sparsification
|
||||
│ │ ├── vertex_split.rs # Vertex split handling with low recourse
|
||||
│ │ ├── contraction.rs # Graph contraction for hierarchy levels
|
||||
│ │ └── queries/ # Cut-based query implementations
|
||||
│ │ ├── mod.rs
|
||||
│ │ ├── all_pairs_mincut.rs
|
||||
│ │ ├── sparsest_cut.rs
|
||||
│ │ ├── multiway_cut.rs
|
||||
│ │ └── multicut.rs
|
||||
│ ├── tiered/ # NEW: Two-tier coordination
|
||||
│ │ ├── mod.rs
|
||||
│ │ ├── coordinator.rs # Tier 1/Tier 2 routing logic
|
||||
│ │ ├── trigger.rs # Escalation trigger policies
|
||||
│ │ └── cache.rs # Cross-tier result caching
|
||||
│ └── ...existing modules...
|
||||
```
|
||||
|
||||
### Core Data Structures
|
||||
|
||||
#### j-Tree Hierarchy
|
||||
|
||||
```rust
|
||||
/// Hierarchical j-tree decomposition for approximate cut structure
|
||||
pub struct JTreeHierarchy {
|
||||
/// Number of levels (L = O(log n / log α))
|
||||
levels: usize,
|
||||
/// Approximation quality per level
|
||||
alpha: f64,
|
||||
/// Contracted graphs at each level
|
||||
contracted_graphs: Vec<ContractedGraph>,
|
||||
/// Cut sparsifier backbone
|
||||
sparsifier: DynamicCutSparsifier,
|
||||
/// j-trees at each level
|
||||
jtrees: Vec<JTree>,
|
||||
}
|
||||
|
||||
/// Single level j-tree
|
||||
pub struct JTree {
|
||||
/// Tree structure
|
||||
tree: DynamicTree,
|
||||
/// Mapping from original vertices to tree nodes
|
||||
vertex_map: HashMap<VertexId, TreeNodeId>,
|
||||
/// Cached cut values between tree nodes
|
||||
cut_cache: CutCache,
|
||||
/// Level index
|
||||
level: usize,
|
||||
}
|
||||
|
||||
impl JTreeHierarchy {
|
||||
/// Build hierarchy from graph
|
||||
pub fn build(graph: &DynamicGraph, epsilon: f64) -> Self {
|
||||
let alpha = compute_alpha(epsilon);
|
||||
let levels = (graph.vertex_count() as f64).log(alpha as f64).ceil() as usize;
|
||||
|
||||
// Build sparsifier first
|
||||
let sparsifier = DynamicCutSparsifier::build(graph, epsilon);
|
||||
|
||||
// Build contracted graphs level by level
|
||||
let mut contracted_graphs = Vec::with_capacity(levels);
|
||||
let mut current = sparsifier.sparse_graph();
|
||||
|
||||
for level in 0..levels {
|
||||
contracted_graphs.push(current.clone());
|
||||
current = contract_to_jtree(¤t, alpha);
|
||||
}
|
||||
|
||||
Self {
|
||||
levels,
|
||||
alpha,
|
||||
contracted_graphs,
|
||||
sparsifier,
|
||||
jtrees: build_jtrees(&contracted_graphs),
|
||||
}
|
||||
}
|
||||
|
||||
/// Insert edge with O(n^ε) amortized update
|
||||
pub fn insert_edge(&mut self, u: VertexId, v: VertexId, weight: f64) -> Result<(), Error> {
|
||||
// Update sparsifier (handles vertex splits internally)
|
||||
self.sparsifier.insert_edge(u, v, weight)?;
|
||||
|
||||
// Propagate through hierarchy levels
|
||||
for level in 0..self.levels {
|
||||
self.update_level(level, EdgeUpdate::Insert(u, v, weight))?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Delete edge with O(n^ε) amortized update
|
||||
pub fn delete_edge(&mut self, u: VertexId, v: VertexId) -> Result<(), Error> {
|
||||
self.sparsifier.delete_edge(u, v)?;
|
||||
|
||||
for level in 0..self.levels {
|
||||
self.update_level(level, EdgeUpdate::Delete(u, v))?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Query approximate min-cut (poly-log approximation)
|
||||
pub fn approximate_min_cut(&self) -> ApproximateCut {
|
||||
// Start from root level and refine
|
||||
let mut cut = self.jtrees[self.levels - 1].min_cut();
|
||||
|
||||
for level in (0..self.levels - 1).rev() {
|
||||
cut = self.jtrees[level].refine_cut(&cut);
|
||||
}
|
||||
|
||||
ApproximateCut {
|
||||
value: cut.value,
|
||||
approximation_factor: self.alpha.powi(self.levels as i32),
|
||||
partition: cut.partition,
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Vertex-Split-Tolerant Cut Sparsifier
|
||||
|
||||
```rust
|
||||
/// Dynamic cut sparsifier with low recourse under vertex splits
|
||||
pub struct DynamicCutSparsifier {
|
||||
/// Forest packing for edge sampling
|
||||
forest_packing: ForestPacking,
|
||||
/// Sparse graph maintaining (1±ε) cut approximation
|
||||
sparse_graph: DynamicGraph,
|
||||
/// Epsilon parameter
|
||||
epsilon: f64,
|
||||
/// Recourse counter for complexity verification
|
||||
recourse: RecourseTracker,
|
||||
}
|
||||
|
||||
impl DynamicCutSparsifier {
|
||||
/// Handle vertex split with poly-log recourse
|
||||
pub fn split_vertex(&mut self, v: VertexId, v1: VertexId, v2: VertexId,
|
||||
partition: &[EdgeId]) -> Result<RecourseStats, Error> {
|
||||
let before_edges = self.sparse_graph.edge_count();
|
||||
|
||||
// Forest packing handles the split
|
||||
let affected_forests = self.forest_packing.split_vertex(v, v1, v2, partition)?;
|
||||
|
||||
// Lazy repair: only fix forests that actually need it
|
||||
for forest_id in affected_forests {
|
||||
self.repair_forest(forest_id)?;
|
||||
}
|
||||
|
||||
let recourse = (self.sparse_graph.edge_count() as i64 - before_edges as i64).abs();
|
||||
self.recourse.record(recourse as usize);
|
||||
|
||||
Ok(self.recourse.stats())
|
||||
}
|
||||
|
||||
/// The key insight: forest packing limits cascading updates
|
||||
fn repair_forest(&mut self, forest_id: ForestId) -> Result<(), Error> {
|
||||
// Only O(log n) edges need adjustment per forest
|
||||
// Total forests = O(log n / ε²)
|
||||
// Total recourse = O(log² n / ε²) per vertex split
|
||||
self.forest_packing.repair(forest_id, &mut self.sparse_graph)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Two-Tier Coordinator
|
||||
|
||||
```rust
|
||||
/// Coordinates between j-tree approximation (Tier 1) and exact min-cut (Tier 2)
|
||||
pub struct TwoTierCoordinator {
|
||||
/// Tier 1: Fast approximate hierarchy
|
||||
jtree: JTreeHierarchy,
|
||||
/// Tier 2: Exact min-cut for verification
|
||||
exact: SubpolynomialMinCut,
|
||||
/// Trigger policy for escalation
|
||||
trigger: EscalationTrigger,
|
||||
/// Result cache to avoid redundant computation
|
||||
cache: TierCache,
|
||||
}
|
||||
|
||||
/// When to escalate from Tier 1 to Tier 2
|
||||
pub struct EscalationTrigger {
|
||||
/// Approximate cut threshold below which we verify exactly
|
||||
critical_threshold: f64,
|
||||
/// Maximum approximation factor before requiring exact
|
||||
max_approx_factor: f64,
|
||||
/// Whether the query requires exact answer
|
||||
exact_required: bool,
|
||||
}
|
||||
|
||||
impl TwoTierCoordinator {
|
||||
/// Query min-cut with tiered strategy
|
||||
pub fn min_cut(&mut self, exact_required: bool) -> CutResult {
|
||||
// Check cache first
|
||||
if let Some(cached) = self.cache.get() {
|
||||
if !exact_required || cached.is_exact {
|
||||
return cached.clone();
|
||||
}
|
||||
}
|
||||
|
||||
// Tier 1: Fast approximate query
|
||||
let approx = self.jtree.approximate_min_cut();
|
||||
|
||||
// Decide whether to escalate
|
||||
let should_escalate = exact_required
|
||||
|| approx.value < self.trigger.critical_threshold
|
||||
|| approx.approximation_factor > self.trigger.max_approx_factor;
|
||||
|
||||
if should_escalate {
|
||||
// Tier 2: Exact verification
|
||||
let exact_value = self.exact.min_cut_value();
|
||||
let exact_partition = self.exact.partition();
|
||||
|
||||
let result = CutResult {
|
||||
value: exact_value,
|
||||
partition: exact_partition,
|
||||
is_exact: true,
|
||||
approximation_factor: 1.0,
|
||||
tier_used: Tier::Exact,
|
||||
};
|
||||
|
||||
self.cache.store(result.clone());
|
||||
result
|
||||
} else {
|
||||
let result = CutResult {
|
||||
value: approx.value,
|
||||
partition: approx.partition,
|
||||
is_exact: false,
|
||||
approximation_factor: approx.approximation_factor,
|
||||
tier_used: Tier::Approximate,
|
||||
};
|
||||
|
||||
self.cache.store(result.clone());
|
||||
result
|
||||
}
|
||||
}
|
||||
|
||||
/// Insert edge, updating both tiers
|
||||
pub fn insert_edge(&mut self, u: VertexId, v: VertexId, weight: f64) -> Result<(), Error> {
|
||||
self.cache.invalidate();
|
||||
|
||||
// Update Tier 1 (fast)
|
||||
self.jtree.insert_edge(u, v, weight)?;
|
||||
|
||||
// Update Tier 2 (also fast, but only if we're tracking that edge regime)
|
||||
self.exact.insert_edge(u, v, weight)?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Extended Query Support
|
||||
|
||||
The j-tree hierarchy enables queries beyond min-cut:
|
||||
|
||||
```rust
|
||||
impl JTreeHierarchy {
|
||||
/// All-pairs minimum cuts (approximate)
|
||||
pub fn all_pairs_min_cuts(&self) -> AllPairsResult {
|
||||
// Use hierarchy to avoid O(n²) explicit computation
|
||||
// Query time: O(n log n) for all pairs
|
||||
let mut results = HashMap::new();
|
||||
|
||||
for (u, v) in self.vertex_pairs() {
|
||||
let cut = self.min_cut_between(u, v);
|
||||
results.insert((u, v), cut);
|
||||
}
|
||||
|
||||
AllPairsResult { cuts: results }
|
||||
}
|
||||
|
||||
/// Sparsest cut (approximate)
|
||||
pub fn sparsest_cut(&self) -> SparsestCutResult {
|
||||
// Leverage hierarchy for O(n^ε) approximate sparsest cut
|
||||
let mut best_sparsity = f64::INFINITY;
|
||||
let mut best_cut = None;
|
||||
|
||||
for level in 0..self.levels {
|
||||
let candidate = self.jtrees[level].sparsest_cut_candidate();
|
||||
let sparsity = candidate.value / candidate.size.min() as f64;
|
||||
|
||||
if sparsity < best_sparsity {
|
||||
best_sparsity = sparsity;
|
||||
best_cut = Some(candidate);
|
||||
}
|
||||
}
|
||||
|
||||
SparsestCutResult {
|
||||
cut: best_cut.unwrap(),
|
||||
sparsity: best_sparsity,
|
||||
approximation: self.alpha.powi(self.levels as i32),
|
||||
}
|
||||
}
|
||||
|
||||
/// Multi-way cut (approximate)
|
||||
pub fn multiway_cut(&self, terminals: &[VertexId]) -> MultiwayCutResult {
|
||||
// Use j-tree hierarchy to find approximate multiway cut
|
||||
// Approximation: O(log k) where k = number of terminals
|
||||
self.compute_multiway_cut(terminals)
|
||||
}
|
||||
|
||||
/// Multi-cut (approximate)
|
||||
pub fn multicut(&self, pairs: &[(VertexId, VertexId)]) -> MulticutResult {
|
||||
// Approximate multicut using hierarchy
|
||||
self.compute_multicut(pairs)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Integration with Coherence Gate (ADR-001)
|
||||
|
||||
The j-tree hierarchy integrates with the Anytime-Valid Coherence Gate:
|
||||
|
||||
```rust
|
||||
/// Enhanced coherence gate using two-tier cut architecture
|
||||
pub struct TieredCoherenceGate {
|
||||
/// Two-tier cut coordinator
|
||||
cut_coordinator: TwoTierCoordinator,
|
||||
/// Conformal prediction component
|
||||
conformal: ShiftAdaptiveConformal,
|
||||
/// E-process evidence accumulator
|
||||
evidence: EProcessAccumulator,
|
||||
/// Gate thresholds
|
||||
thresholds: GateThresholds,
|
||||
}
|
||||
|
||||
impl TieredCoherenceGate {
|
||||
/// Fast structural check using Tier 1
|
||||
pub fn fast_structural_check(&self, action: &Action) -> QuickDecision {
|
||||
// Use j-tree for O(n^ε) approximate check
|
||||
let approx_cut = self.cut_coordinator.jtree.approximate_min_cut();
|
||||
|
||||
if approx_cut.value > self.thresholds.definitely_safe {
|
||||
QuickDecision::Permit
|
||||
} else if approx_cut.value < self.thresholds.definitely_unsafe {
|
||||
QuickDecision::Deny
|
||||
} else {
|
||||
QuickDecision::NeedsExactCheck
|
||||
}
|
||||
}
|
||||
|
||||
/// Full evaluation with exact verification if needed
|
||||
pub fn evaluate(&mut self, action: &Action, context: &Context) -> GateDecision {
|
||||
// Quick check first
|
||||
let quick = self.fast_structural_check(action);
|
||||
|
||||
match quick {
|
||||
QuickDecision::Permit => {
|
||||
// Fast path: structure is definitely safe
|
||||
self.issue_permit_fast(action)
|
||||
}
|
||||
QuickDecision::Deny => {
|
||||
// Fast path: structure is definitely unsafe
|
||||
self.issue_denial_fast(action)
|
||||
}
|
||||
QuickDecision::NeedsExactCheck => {
|
||||
// Invoke Tier 2 for exact verification
|
||||
let exact_cut = self.cut_coordinator.min_cut(true);
|
||||
self.evaluate_with_exact_cut(action, context, exact_cut)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Characteristics
|
||||
|
||||
| Operation | Tier 1 (j-Tree) | Tier 2 (Exact) | Combined |
|
||||
|-----------|-----------------|----------------|----------|
|
||||
| **Insert Edge** | O(n^ε) | O(n^{o(1)}) | O(n^ε) |
|
||||
| **Delete Edge** | O(n^ε) | O(n^{o(1)}) | O(n^ε) |
|
||||
| **Min-Cut Query** | O(log n) approx | O(1) exact | O(1) - O(log n) |
|
||||
| **All-Pairs Min-Cut** | O(n log n) | N/A | O(n log n) |
|
||||
| **Sparsest Cut** | O(n^ε) | N/A | O(n^ε) |
|
||||
| **Multi-Way Cut** | O(k log k · n^ε) | N/A | O(k log k · n^ε) |
|
||||
|
||||
### Recourse Guarantees
|
||||
|
||||
The vertex-split-tolerant sparsifier provides:
|
||||
|
||||
| Metric | Guarantee |
|
||||
|--------|-----------|
|
||||
| **Edges adjusted per update** | O(log² n / ε²) |
|
||||
| **Total recourse over m updates** | O(m · log² n / ε²) |
|
||||
| **Forest repairs per vertex split** | O(log n) |
|
||||
|
||||
This is critical for maintaining hierarchy stability under dynamic changes.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Core Sparsifier (Weeks 1-3)
|
||||
|
||||
- [ ] Implement `ForestPacking` with edge sampling
|
||||
- [ ] Implement `DynamicCutSparsifier` with vertex split handling
|
||||
- [ ] Add recourse tracking and verification
|
||||
- [ ] Unit tests for sparsifier correctness
|
||||
|
||||
### Phase 2: j-Tree Hierarchy (Weeks 4-6)
|
||||
|
||||
- [ ] Implement `JTree` single-level structure
|
||||
- [ ] Implement `JTreeHierarchy` multi-level decomposition
|
||||
- [ ] Add contraction algorithms for level construction
|
||||
- [ ] Integration tests for hierarchy maintenance
|
||||
|
||||
### Phase 3: Query Support (Weeks 7-9)
|
||||
|
||||
- [ ] Implement approximate min-cut queries
|
||||
- [ ] Implement all-pairs min-cut
|
||||
- [ ] Implement sparsest cut
|
||||
- [ ] Implement multi-way cut and multi-cut
|
||||
- [ ] Benchmark query performance
|
||||
|
||||
### Phase 4: Two-Tier Integration (Weeks 10-12)
|
||||
|
||||
- [ ] Implement `TwoTierCoordinator`
|
||||
- [ ] Define escalation trigger policies
|
||||
- [ ] Integrate with coherence gate
|
||||
- [ ] End-to-end testing with coherence scenarios
|
||||
|
||||
---
|
||||
|
||||
## Feature Flags
|
||||
|
||||
```toml
|
||||
[features]
|
||||
# Existing features
|
||||
default = ["exact", "approximate"]
|
||||
exact = []
|
||||
approximate = []
|
||||
|
||||
# New features
|
||||
jtree = [] # j-Tree hierarchical decomposition
|
||||
tiered = ["jtree", "exact"] # Two-tier coordinator
|
||||
all-cut-queries = ["jtree"] # Sparsest cut, multiway, multicut
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Benefits
|
||||
|
||||
1. **Broader Query Support**: Sparsest cut, multi-way cut, multi-cut, all-pairs - not just minimum cut
|
||||
2. **Faster Continuous Monitoring**: O(n^ε) updates enable 10K+ updates/second even on large graphs
|
||||
3. **Global Structure Awareness**: Hierarchical view shows cut landscape at multiple scales
|
||||
4. **Graceful Degradation**: Approximate answers when exact isn't needed, exact when it is
|
||||
5. **Low Recourse**: Sparsifier stability prevents update cascades
|
||||
6. **Coherence Gate Enhancement**: Fast structural checks with exact fallback
|
||||
|
||||
### Risks & Mitigations
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|-------------|--------|------------|
|
||||
| Implementation complexity | High | Medium | Phase incrementally, extensive testing |
|
||||
| Approximation too loose | Medium | Medium | Tunable α parameter, exact fallback |
|
||||
| Memory overhead from hierarchy | Medium | Low | Lazy level construction |
|
||||
| Integration complexity with existing code | Medium | Medium | Clean interface boundaries |
|
||||
|
||||
### Complexity Analysis
|
||||
|
||||
| Component | Space | Time (Update) | Time (Query) |
|
||||
|-----------|-------|---------------|--------------|
|
||||
| Forest Packing | O(m log n / ε²) | O(log² n / ε²) | O(1) |
|
||||
| j-Tree Level | O(n_ℓ) | O(n_ℓ^ε) | O(log n_ℓ) |
|
||||
| Full Hierarchy | O(n log n) | O(n^ε) | O(log n) |
|
||||
| Two-Tier Cache | O(n) | O(1) | O(1) |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
### Primary
|
||||
|
||||
1. Goranci, G., Henzinger, M., Kiss, P., Momeni, A., & Zöcklein, G. (January 2026). "Dynamic Hierarchical j-Tree Decomposition and Its Applications." *arXiv:2601.09139*. SODA 2026. **[Core paper for this ADR]**
|
||||
|
||||
### Complementary
|
||||
|
||||
2. El-Hayek, A., Henzinger, M., & Li, J. (December 2025). "Deterministic and Exact Fully-dynamic Minimum Cut of Superpolylogarithmic Size in Subpolynomial Time." *arXiv:2512.13105*. **[Existing Tier 2 implementation]**
|
||||
|
||||
3. Mądry, A. (2010). "Fast Approximation Algorithms for Cut-Based Problems in Undirected Graphs." *FOCS 2010*. **[Original j-tree decomposition]**
|
||||
|
||||
### Background
|
||||
|
||||
4. Benczúr, A. A., & Karger, D. R. (1996). "Approximating s-t Minimum Cuts in Õ(n²) Time." *STOC*. **[Cut sparsification foundations]**
|
||||
|
||||
5. Thorup, M. (2007). "Fully-Dynamic Min-Cut." *Combinatorica*. **[Dynamic min-cut foundations]**
|
||||
|
||||
---
|
||||
|
||||
## Related Decisions
|
||||
|
||||
- **ADR-001**: Anytime-Valid Coherence Gate (uses Tier 2 exact min-cut)
|
||||
- **ADR-014**: Coherence Engine Architecture (coherence computation)
|
||||
- **ADR-CE-001**: Sheaf Laplacian Coherence (structural coherence foundation)
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Paper Comparison
|
||||
|
||||
### El-Hayek/Henzinger/Li (Dec 2025) vs Goranci et al. (Jan 2026)
|
||||
|
||||
| Aspect | arXiv:2512.13105 | arXiv:2601.09139 |
|
||||
|--------|------------------|------------------|
|
||||
| **Focus** | Exact min-cut | Approximate cut hierarchy |
|
||||
| **Update Time** | O(n^{o(1)}) | O(n^ε) for any ε > 0 |
|
||||
| **Approximation** | Exact | Poly-logarithmic |
|
||||
| **Cut Regime** | Superpolylogarithmic | All sizes |
|
||||
| **Query Types** | Min-cut only | All cut problems |
|
||||
| **Deterministic** | Yes | Yes |
|
||||
| **Key Technique** | Cluster hierarchy + LocalKCut | j-Tree + vertex-split sparsifier |
|
||||
|
||||
**Synergy**: The two approaches complement each other perfectly:
|
||||
- Use Goranci et al. for fast global monitoring and diverse cut queries
|
||||
- Use El-Hayek et al. for exact verification when critical cuts are detected
|
||||
|
||||
This two-tier strategy provides both breadth (approximate queries on all cut problems) and depth (exact min-cut when needed).
|
||||
392
vendor/ruvector/crates/ruvector-mincut/docs/adr/APPENDIX-applications-spectrum.md
vendored
Normal file
392
vendor/ruvector/crates/ruvector-mincut/docs/adr/APPENDIX-applications-spectrum.md
vendored
Normal file
@@ -0,0 +1,392 @@
|
||||
# Appendix: Applications Spectrum for Anytime-Valid Coherence Gate
|
||||
|
||||
**Related**: ADR-001, DDC-001, ROADMAP
|
||||
|
||||
This appendix maps the Anytime-Valid Coherence Gate to concrete market applications across three horizons.
|
||||
|
||||
---
|
||||
|
||||
## Practical Applications (0-18 months)
|
||||
|
||||
These convert pilots into procurement. Target: Enterprise buyers who need auditable safety now.
|
||||
|
||||
### 1. Network Security Control Plane
|
||||
|
||||
**Use Case**: Detect and suppress lateral movement, credential abuse, and tool misuse in real time.
|
||||
|
||||
**How the Gate Helps**:
|
||||
- When coherence drops (new relationships, weird graph cuts, novel access paths), actions get deferred or denied automatically
|
||||
- Witness partitions identify the exact boundary crossing that triggered intervention
|
||||
- E-process accumulates evidence of anomalous behavior over time
|
||||
|
||||
**Demo Scenario**:
|
||||
```
|
||||
1. Ingest NetFlow + auth logs into RuVector graph
|
||||
2. Fire simulated attack (credential stuffing → lateral movement)
|
||||
3. Show Permit/Deny decisions with witness cut visualization
|
||||
4. Highlight "here's exactly why this action was blocked"
|
||||
```
|
||||
|
||||
**Metric to Own**: Mean time to safe containment (MTTC)
|
||||
|
||||
**Integration Points**:
|
||||
- SIEM integration via `GatePacket` events
|
||||
- Witness receipts feed into incident response workflows
|
||||
- E-process thresholds map to SOC escalation tiers
|
||||
|
||||
---
|
||||
|
||||
### 2. Cloud Operations Autopilot
|
||||
|
||||
**Use Case**: Auto-remediation of incidents without runaway automation.
|
||||
|
||||
**How the Gate Helps**:
|
||||
- Only allow remediation steps that stay inside stable partitions of dependency graphs
|
||||
- Coherence drop triggers "Defer to human" instead of cascading rollback
|
||||
- Conformal prediction sets quantify uncertainty about remediation outcomes
|
||||
|
||||
**Demo Scenario**:
|
||||
```
|
||||
1. Service dependency graph + deploy pipeline in RuVector
|
||||
2. Inject failure (service A crashes)
|
||||
3. Autopilot proposes rollback
|
||||
4. Gate checks: "Does rollback stay within stable partition?"
|
||||
5. If boundary crossing detected → DEFER with witness
|
||||
```
|
||||
|
||||
**Metric to Own**: Reduction in incident blast radius
|
||||
|
||||
**Integration Points**:
|
||||
- Kubernetes operator for deployment gating
|
||||
- Terraform plan validation via graph analysis
|
||||
- PagerDuty integration for DEFER escalations
|
||||
|
||||
---
|
||||
|
||||
### 3. Data Governance and Exfiltration Prevention
|
||||
|
||||
**Use Case**: Prevent agents from leaking sensitive data across boundaries.
|
||||
|
||||
**How the Gate Helps**:
|
||||
- Boundary witnesses become enforceable "do not cross" lines
|
||||
- Memory shards and tool scopes mapped as graph partitions
|
||||
- Any action crossing partition → immediate DENY + audit
|
||||
|
||||
**Metric to Own**: Unauthorized cross-domain action suppression rate
|
||||
|
||||
**Architecture**:
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ PII Zone │ │ Public Zone │
|
||||
│ (Partition A) │ │ (Partition B) │
|
||||
│ │ │ │
|
||||
│ • User records │ │ • Analytics │
|
||||
│ • Credentials │ │ • Reports │
|
||||
└────────┬────────┘ └────────┬────────┘
|
||||
│ │
|
||||
└──────┬───────────────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ COHERENCE │
|
||||
│ GATE │
|
||||
│ │
|
||||
│ Witness: │
|
||||
│ "Action │
|
||||
│ crosses │
|
||||
│ PII→Public" │
|
||||
│ │
|
||||
│ Decision: │
|
||||
│ DENY │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Agent Routing and Budget Control
|
||||
|
||||
**Use Case**: Stop agents from spiraling, chattering, or tool thrashing.
|
||||
|
||||
**How the Gate Helps**:
|
||||
- Coherence signal detects when agent is "lost" (exploration without progress)
|
||||
- E-value evidence decides whether escalation/continuation is justified
|
||||
- Conformal sets bound expected cost of next action
|
||||
|
||||
**Metric to Own**: Cost per resolved task with fixed safety constraints
|
||||
|
||||
**Decision Logic**:
|
||||
```
|
||||
IF action_count > threshold AND coherence < target:
|
||||
→ Check e-process: "Is progress being made?"
|
||||
→ IF e_value < τ_deny: DENY (stop the spiral)
|
||||
→ IF e_value < τ_permit: DEFER (escalate to human)
|
||||
→ ELSE: PERMIT (continue but monitor)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Practical (18 months - 3 years)
|
||||
|
||||
These start to look like "new infrastructure."
|
||||
|
||||
### 5. Autonomous SOC and NOC
|
||||
|
||||
**Use Case**: Always-on detection, triage, and response with bounded actions.
|
||||
|
||||
**How the Gate Helps**:
|
||||
- System stays calm until boundary crossings spike
|
||||
- Then concentrates attention on anomalous regions
|
||||
- Human analysts handle DEFER decisions only
|
||||
|
||||
**Metric to Own**: Analyst-hours saved per month without increased risk
|
||||
|
||||
**Architecture**:
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ AUTONOMOUS SOC │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ Detect │──▶│ Triage │──▶│ Respond │──▶│ Learn │ │
|
||||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ └─────────────┴─────────────┴─────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼──────┐ │
|
||||
│ │ COHERENCE │ │
|
||||
│ │ GATE │ │
|
||||
│ └──────┬──────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────────┼──────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ PERMIT DEFER DENY │
|
||||
│ (automated) (to analyst) (blocked) │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Supply Chain Integrity and Firmware Trust
|
||||
|
||||
**Use Case**: Devices that self-audit software changes and refuse unsafe upgrades.
|
||||
|
||||
**How the Gate Helps**:
|
||||
- Signed event logs feed into coherence computation
|
||||
- Deterministic replay verifies state transitions
|
||||
- Boundary gating on what updates may alter
|
||||
|
||||
**Metric to Own**: Mean time to recover from compromised update attempt
|
||||
|
||||
**Witness Receipt Structure**:
|
||||
```json
|
||||
{
|
||||
"update_id": "firmware-v2.3.1",
|
||||
"source_hash": "abc123...",
|
||||
"coherence_before": 0.95,
|
||||
"coherence_after_sim": 0.72,
|
||||
"boundary_violations": [
|
||||
"bootloader partition",
|
||||
"secure enclave boundary"
|
||||
],
|
||||
"decision": "DENY",
|
||||
"e_value": 0.003,
|
||||
"receipt_hash": "def456..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Multi-Tenant AI Safety Partitioning
|
||||
|
||||
**Use Case**: Same hardware, many customers, no cross-tenant drift or bleed.
|
||||
|
||||
**How the Gate Helps**:
|
||||
- RuVector partitions model tenant boundaries
|
||||
- Cut-witness enforcement prevents cross-tenant actions
|
||||
- Per-tenant e-processes track coherence independently
|
||||
|
||||
**Metric to Own**: Cross-tenant anomaly leakage probability (measured, not promised)
|
||||
|
||||
**Guarantee Structure**:
|
||||
```
|
||||
For each tenant T_i:
|
||||
P(action from T_i affects T_j, j≠i) ≤ ε
|
||||
|
||||
Where ε is bounded by:
|
||||
- Min-cut between T_i and T_j partitions
|
||||
- Conformal prediction set overlap
|
||||
- E-process independence verification
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exotic Applications (3-10 years)
|
||||
|
||||
These are the ones that make people say "wait, that's a different kind of computer."
|
||||
|
||||
### 8. Machines that "Refuse to Hallucinate with Actions"
|
||||
|
||||
**Use Case**: A system that can still be uncertain, but cannot act uncertainly.
|
||||
|
||||
**Principle**:
|
||||
- It can generate hypotheses all day
|
||||
- But action requires coherence AND evidence
|
||||
- Creativity without incident
|
||||
|
||||
**How It Works**:
|
||||
```
|
||||
WHILE generating:
|
||||
hypotheses ← LLM.generate() # Unconstrained creativity
|
||||
|
||||
FOR action in proposed_actions:
|
||||
IF NOT coherence_gate.permits(action):
|
||||
CONTINUE # Skip uncertain actions
|
||||
|
||||
# Only reaches here if:
|
||||
# 1. Action stays in stable partition
|
||||
# 2. Conformal set is small (confident prediction)
|
||||
# 3. E-process shows sufficient evidence
|
||||
|
||||
EXECUTE(action)
|
||||
```
|
||||
|
||||
**Outcome**: You get creativity without incident. The system can explore freely in thought-space but must be grounded before acting.
|
||||
|
||||
---
|
||||
|
||||
### 9. Continuous Self-Healing Software and Infrastructure
|
||||
|
||||
**Use Case**: Systems that grow calmer over time, not more fragile.
|
||||
|
||||
**Principle**:
|
||||
- Coherence becomes the homeostasis signal
|
||||
- Learning pauses when unstable, resumes when stable
|
||||
- Optimization is built-in, not bolt-on
|
||||
|
||||
**Homeostasis Loop**:
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ │
|
||||
│ ┌─────────┐ │
|
||||
│ │ Observe │◀──────────────────┐ │
|
||||
│ └────┬────┘ │ │
|
||||
│ │ │ │
|
||||
│ ▼ │ │
|
||||
│ ┌─────────┐ │ │
|
||||
│ │ Compute │──▶ coherence │ │
|
||||
│ │Coherence│ │ │
|
||||
│ └────┬────┘ │ │
|
||||
│ │ │ │
|
||||
│ ▼ │ │
|
||||
│ ┌─────────────────────┐ │ │
|
||||
│ │ coherence > target? │ │ │
|
||||
│ └──────────┬──────────┘ │ │
|
||||
│ │ │ │
|
||||
│ ┌──────┴──────┐ │ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ │ │
|
||||
│ ┌───────┐ ┌────────┐ │ │
|
||||
│ │ LEARN │ │ PAUSE │ │ │
|
||||
│ └───┬───┘ └────────┘ │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Outcome**: "Built-in optimization" instead of built-in obsolescence. Systems that maintain themselves.
|
||||
|
||||
---
|
||||
|
||||
### 10. Nervous-System Computing for Fleets
|
||||
|
||||
**Use Case**: Millions of devices that coordinate without central control.
|
||||
|
||||
**Principle**:
|
||||
- Local coherence gates at each node
|
||||
- Only boundary deltas shared upstream
|
||||
- Scale without noise
|
||||
|
||||
**Architecture**:
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ GLOBAL AGGREGATE │
|
||||
│ (boundary deltas only) │
|
||||
└──────────────────┬──────────────────┘
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌───────────┐ ┌───────────┐ ┌───────────┐
|
||||
│ Region A │ │ Region B │ │ Region C │
|
||||
│ Gate │ │ Gate │ │ Gate │
|
||||
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
|
||||
│ │ │
|
||||
┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
|
||||
│ • • • • • │ │ • • • • • │ │ • • • • • │
|
||||
│ Devices │ │ Devices │ │ Devices │
|
||||
│ (local │ │ (local │ │ (local │
|
||||
│ gates) │ │ gates) │ │ gates) │
|
||||
└───────────┘ └───────────┘ └───────────┘
|
||||
```
|
||||
|
||||
**Key Insight**: Most decisions stay local. Only boundary crossings escalate. This is how biological nervous systems achieve scale—not by centralizing everything, but by making most decisions locally and only propagating what matters.
|
||||
|
||||
**Outcome**: Scale without noise. Decisions stay local, escalation stays rare.
|
||||
|
||||
---
|
||||
|
||||
### 11. Synthetic Institutions
|
||||
|
||||
**Use Case**: Autonomous org-like systems that maintain rules, budgets, and integrity over decades.
|
||||
|
||||
**Principle**:
|
||||
- Deterministic governance receipts become the operating fabric
|
||||
- Every decision has a witness
|
||||
- Institutional memory is cryptographically anchored
|
||||
|
||||
**What This Looks Like**:
|
||||
```
|
||||
SYNTHETIC INSTITUTION
|
||||
├── Constitution (immutable rules)
|
||||
│ └── Encoded as min-cut constraints
|
||||
│
|
||||
├── Governance (decision procedures)
|
||||
│ └── Gate policies with e-process thresholds
|
||||
│
|
||||
├── Memory (institutional history)
|
||||
│ └── Merkle tree of witness receipts
|
||||
│
|
||||
├── Budget (resource allocation)
|
||||
│ └── Conformal bounds on expenditure
|
||||
│
|
||||
└── Evolution (rule changes)
|
||||
└── Requires super-majority e-process evidence
|
||||
```
|
||||
|
||||
**Outcome**: A new class of durable, auditable autonomy. Organizations that can outlive their creators while remaining accountable.
|
||||
|
||||
---
|
||||
|
||||
## Summary: The Investment Thesis
|
||||
|
||||
| Horizon | Applications | Market Signal |
|
||||
|---------|--------------|---------------|
|
||||
| **0-18 months** | Network security, cloud ops, data governance, agent routing | "Buyers will pay for this next quarter" |
|
||||
| **18 months - 3 years** | Autonomous SOC/NOC, supply chain, multi-tenant AI | "New infrastructure" |
|
||||
| **3-10 years** | Action-grounded AI, self-healing systems, fleet nervous systems, synthetic institutions | "A different kind of computer" |
|
||||
|
||||
The coherence gate is the primitive that enables all of these. It converts the category thesis (bounded autonomy with receipts) into a product primitive that:
|
||||
1. **Buyers understand**: "Permit / Defer / Deny with audit trail"
|
||||
2. **Auditors accept**: "Every decision has a cryptographic witness"
|
||||
3. **Engineers can build on**: "Clear API with formal guarantees"
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Phase 1 Demo**: Network security control plane (shortest path to revenue)
|
||||
2. **Phase 2 Platform**: Agent routing SDK (developer adoption)
|
||||
3. **Phase 3 Infrastructure**: Multi-tenant AI safety (enterprise lock-in)
|
||||
4. **Phase 4 Research**: Exotic applications (thought leadership)
|
||||
370
vendor/ruvector/crates/ruvector-mincut/docs/adr/DDC-001-coherence-gate-design-criteria.md
vendored
Normal file
370
vendor/ruvector/crates/ruvector-mincut/docs/adr/DDC-001-coherence-gate-design-criteria.md
vendored
Normal file
@@ -0,0 +1,370 @@
|
||||
# DDC-001: Anytime-Valid Coherence Gate - Design Decision Criteria
|
||||
|
||||
**Version**: 1.0
|
||||
**Date**: 2026-01-17
|
||||
**Related ADR**: ADR-001-anytime-valid-coherence-gate
|
||||
|
||||
## Purpose
|
||||
|
||||
This document specifies the design decision criteria for implementing the Anytime-Valid Coherence Gate (AVCG). It provides concrete guidance for architectural choices, implementation trade-offs, and acceptance criteria.
|
||||
|
||||
---
|
||||
|
||||
## 1. Graph Model Design Decisions
|
||||
|
||||
### DDC-1.1: Action Graph Construction
|
||||
|
||||
**Decision Required**: How to construct the action graph G_t from agent state?
|
||||
|
||||
| Option | Description | Pros | Cons | Recommendation |
|
||||
|--------|-------------|------|------|----------------|
|
||||
| **A. State-Action Pairs** | Nodes = (state, action), Edges = transitions | Fine-grained control; precise cuts | Large graphs; O(|S|·|A|) nodes | Use for high-stakes domains |
|
||||
| **B. Abstract State Clusters** | Nodes = state clusters, Edges = aggregate transitions | Smaller graphs; faster updates | May miss nuanced boundaries | **Recommended for v0** |
|
||||
| **C. Learned Embeddings** | Nodes = learned state embeddings | Adaptive; captures latent structure | Requires training data; less interpretable | Future enhancement |
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Graph construction completes in < 100μs for typical agent states
|
||||
- [ ] Graph accurately represents reachability to unsafe states
|
||||
- [ ] Witness partitions are human-interpretable
|
||||
|
||||
### DDC-1.2: Edge Weight Semantics
|
||||
|
||||
**Decision Required**: What do edge weights represent?
|
||||
|
||||
| Option | Interpretation | Use Case |
|
||||
|--------|---------------|----------|
|
||||
| **A. Risk Scores** | Higher weight = higher risk of unsafe outcome | Min-cut = minimum total risk to unsafe |
|
||||
| **B. Inverse Probability** | Higher weight = less likely transition | Min-cut = least likely path to unsafe |
|
||||
| **C. Unit Weights** | All edges weight 1.0 | Min-cut = fewest actions to unsafe |
|
||||
| **D. Conformal Set Size** | Weight = |C_t| for that action | Natural integration with predictive uncertainty |
|
||||
|
||||
**Recommendation**: Option D creates natural integration between min-cut and conformal prediction.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Weight semantics are documented and consistent
|
||||
- [ ] Min-cut value has interpretable meaning for operators
|
||||
- [ ] Weights update correctly on new observations
|
||||
|
||||
---
|
||||
|
||||
## 2. Conformal Predictor Architecture
|
||||
|
||||
### DDC-2.1: Base Predictor Selection
|
||||
|
||||
**Decision Required**: Which base predictor to wrap with conformal prediction?
|
||||
|
||||
| Option | Characteristics | Computational Cost |
|
||||
|--------|----------------|-------------------|
|
||||
| **A. Neural Network** | High capacity; requires calibration | Medium-High |
|
||||
| **B. Random Forest** | Built-in uncertainty; robust | Medium |
|
||||
| **C. Gaussian Process** | Natural uncertainty; O(n³) training | High |
|
||||
| **D. Ensemble with Dropout** | Approximate Bayesian; scalable | Medium |
|
||||
|
||||
**Recommendation**: Option D (Ensemble with Dropout) for balance of capacity and uncertainty.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Base predictor achieves acceptable accuracy on held-out data
|
||||
- [ ] Prediction latency < 10ms for single action
|
||||
- [ ] Uncertainty estimates correlate with actual error rates
|
||||
|
||||
### DDC-2.2: Non-Conformity Score Function
|
||||
|
||||
**Decision Required**: How to compute non-conformity scores?
|
||||
|
||||
| Option | Formula | Properties |
|
||||
|--------|---------|------------|
|
||||
| **A. Absolute Residual** | s(x,y) = |y - ŷ(x)| | Simple; symmetric |
|
||||
| **B. Normalized Residual** | s(x,y) = |y - ŷ(x)| / σ̂(x) | Scale-invariant |
|
||||
| **C. CQR** | s(x,y) = max(q̂_lo - y, y - q̂_hi) | Heteroscedastic coverage |
|
||||
|
||||
**Recommendation**: Option C (CQR) for heteroscedastic agent environments.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Marginal coverage ≥ 1 - α over calibration window
|
||||
- [ ] Conditional coverage approximately uniform across feature space
|
||||
- [ ] Prediction sets are not trivially large
|
||||
|
||||
### DDC-2.3: Shift Adaptation Method
|
||||
|
||||
**Decision Required**: How to adapt conformal predictor to distribution shift?
|
||||
|
||||
| Method | Adaptation Speed | Conservativeness |
|
||||
|--------|-----------------|------------------|
|
||||
| **A. ACI (Adaptive Conformal)** | Medium | High |
|
||||
| **B. Retrospective Adjustment** | Fast | Medium |
|
||||
| **C. COP (Conformal Optimistic)** | Fastest | Low (but valid) |
|
||||
| **D. CORE (RL-based)** | Adaptive | Task-dependent |
|
||||
|
||||
**Recommendation**: Hybrid approach:
|
||||
- Use COP for normal operation (fast, less conservative)
|
||||
- Fall back to ACI under detected severe shift
|
||||
- Use retrospective adjustment for post-hoc correction
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Coverage maintained during gradual shift (δ < 0.1/step)
|
||||
- [ ] Recovery to target coverage within 100 steps after abrupt shift
|
||||
- [ ] No catastrophic coverage failures (coverage never < 0.5)
|
||||
|
||||
---
|
||||
|
||||
## 3. E-Process Construction
|
||||
|
||||
### DDC-3.1: E-Value Computation Method
|
||||
|
||||
**Decision Required**: How to compute per-action e-values?
|
||||
|
||||
| Method | Requirements | Robustness |
|
||||
|--------|--------------|------------|
|
||||
| **A. Likelihood Ratio** | Density models for H₀ and H₁ | Low (model-dependent) |
|
||||
| **B. Universal Inference** | Split data; no density needed | Medium |
|
||||
| **C. Mixture E-Values** | Multiple alternatives | High (hedged) |
|
||||
| **D. Betting E-Values** | Online learning framework | High (adaptive) |
|
||||
|
||||
**Recommendation**: Option C (Mixture E-Values) for robustness:
|
||||
```
|
||||
e_t = (1/K) Σ_k e_t^{(k)}
|
||||
```
|
||||
Where each e_t^{(k)} tests a different alternative hypothesis.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] E[e_t | H₀] ≤ 1 verified empirically
|
||||
- [ ] Power against reasonable alternatives > 0.5
|
||||
- [ ] Computation time < 1ms per e-value
|
||||
|
||||
### DDC-3.2: E-Process Update Rule
|
||||
|
||||
**Decision Required**: How to update the e-process over time?
|
||||
|
||||
| Rule | Formula | Properties |
|
||||
|------|---------|------------|
|
||||
| **A. Product** | E_t = Π_{i=1}^t e_i | Aggressive; exponential power |
|
||||
| **B. Average** | E_t = (1/t) Σ_{i=1}^t e_i | Conservative; bounded |
|
||||
| **C. Exponential Moving** | E_t = λ·e_t + (1-λ)·E_{t-1} | Balanced; forgetting |
|
||||
| **D. Mixture Supermartingale** | E_t = Σ_j w_j · E_t^{(j)} | Robust; hedged |
|
||||
|
||||
**Recommendation**:
|
||||
- Option A (Product) for high-stakes single decisions
|
||||
- Option D (Mixture) for continuous monitoring
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] E_t remains nonnegative supermartingale
|
||||
- [ ] Stopping time τ has valid Type I error: P(E_τ ≥ 1/α) ≤ α
|
||||
- [ ] Power grows with evidence accumulation
|
||||
|
||||
### DDC-3.3: Null Hypothesis Specification
|
||||
|
||||
**Decision Required**: What constitutes the "coherence" null hypothesis?
|
||||
|
||||
| Formulation | Meaning |
|
||||
|-------------|---------|
|
||||
| **A. Action Safety** | H₀: P(action leads to unsafe state) ≤ p₀ |
|
||||
| **B. State Stability** | H₀: P(state deviates from normal) ≤ p₀ |
|
||||
| **C. Policy Consistency** | H₀: Current policy ≈ reference policy |
|
||||
| **D. Composite** | H₀: (A) ∧ (B) ∧ (C) |
|
||||
|
||||
**Recommendation**: Start with Option A, extend to Option D for production.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] H₀ is well-specified and testable
|
||||
- [ ] False alarm rate matches target α
|
||||
- [ ] Null violations are meaningfully dangerous
|
||||
|
||||
---
|
||||
|
||||
## 4. Integration Architecture
|
||||
|
||||
### DDC-4.1: Signal Combination Strategy
|
||||
|
||||
**Decision Required**: How to combine the three signals into a gate decision?
|
||||
|
||||
| Strategy | Logic | Properties |
|
||||
|----------|-------|------------|
|
||||
| **A. Sequential Short-Circuit** | Cut → Conformal → E-process | Fast rejection; ordered |
|
||||
| **B. Parallel with Voting** | All evaluate; majority rules | Robust; slower |
|
||||
| **C. Weighted Integration** | score = w₁·cut + w₂·conf + w₃·e | Flexible; needs tuning |
|
||||
| **D. Hierarchical** | E-process gates conformal gates cut | Layered authority |
|
||||
|
||||
**Recommendation**: Option A (Sequential Short-Circuit):
|
||||
1. Min-cut DENY is immediate (structural safety)
|
||||
2. Conformal uncertainty gates e-process (no point accumulating evidence if outcome unpredictable)
|
||||
3. E-process makes final permit/defer decision
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Gate latency < 50ms for typical decisions
|
||||
- [ ] No single-point-of-failure (graceful degradation)
|
||||
- [ ] Decision audit trail is complete
|
||||
|
||||
### DDC-4.2: Graceful Degradation
|
||||
|
||||
**Decision Required**: How should the gate behave when components fail?
|
||||
|
||||
| Component Failure | Fallback Behavior |
|
||||
|-------------------|-------------------|
|
||||
| Min-cut unavailable | Defer all actions; alert operator |
|
||||
| Conformal predictor fails | Use widened prediction sets (conservative) |
|
||||
| E-process computation fails | Use last valid e-value; decay confidence |
|
||||
| All components fail | Full DENY; require human approval |
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Failure detection within 100ms
|
||||
- [ ] Fallback never less safe than full DENY
|
||||
- [ ] Recovery is automatic when component restores
|
||||
|
||||
### DDC-4.3: Latency Budget Allocation
|
||||
|
||||
**Decision Required**: How to allocate total latency budget across components?
|
||||
|
||||
Given total budget T_total (e.g., 50ms):
|
||||
|
||||
| Component | Allocation | Rationale |
|
||||
|-----------|------------|-----------|
|
||||
| Min-cut update | 0.2 · T | Amortized; subpolynomial |
|
||||
| Conformal prediction | 0.4 · T | Main computation |
|
||||
| E-process update | 0.2 · T | Arithmetic; fast |
|
||||
| Decision logic | 0.1 · T | Simple rules |
|
||||
| Receipt generation | 0.1 · T | Hashing; logging |
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] p99 latency < T_total
|
||||
- [ ] No component exceeds 2× its budget
|
||||
- [ ] Latency monitoring in place
|
||||
|
||||
---
|
||||
|
||||
## 5. Operational Parameters
|
||||
|
||||
### DDC-5.1: Threshold Configuration
|
||||
|
||||
| Parameter | Symbol | Default | Range | Tuning Guidance |
|
||||
|-----------|--------|---------|-------|-----------------|
|
||||
| E-process deny threshold | τ_deny | 0.01 | [0.001, 0.1] | Lower = more conservative |
|
||||
| E-process permit threshold | τ_permit | 100 | [10, 1000] | Higher = more evidence required |
|
||||
| Uncertainty threshold | θ_uncertainty | 0.5 | [0.1, 1.0] | Fraction of outcome space |
|
||||
| Confidence threshold | θ_confidence | 0.1 | [0.01, 0.3] | Fraction of outcome space |
|
||||
| Conformal coverage target | 1-α | 0.9 | [0.8, 0.99] | Higher = larger sets |
|
||||
|
||||
### DDC-5.2: Audit Requirements
|
||||
|
||||
| Requirement | Specification |
|
||||
|-------------|---------------|
|
||||
| Receipt retention | 90 days minimum |
|
||||
| Receipt format | JSON + protobuf |
|
||||
| Receipt signing | Ed25519 signature |
|
||||
| Receipt searchability | Indexed by action_id, timestamp, decision |
|
||||
| Receipt integrity | Merkle tree for batch verification |
|
||||
|
||||
---
|
||||
|
||||
## 6. Testing & Validation Criteria
|
||||
|
||||
### DDC-6.1: Unit Test Coverage
|
||||
|
||||
| Module | Coverage Target | Critical Paths |
|
||||
|--------|-----------------|----------------|
|
||||
| conformal/ | ≥ 90% | Prediction set generation; shift adaptation |
|
||||
| eprocess/ | ≥ 95% | E-value validity; supermartingale property |
|
||||
| anytime_gate/ | ≥ 90% | Decision logic; receipt generation |
|
||||
|
||||
### DDC-6.2: Integration Test Scenarios
|
||||
|
||||
| Scenario | Expected Behavior |
|
||||
|----------|-------------------|
|
||||
| Normal operation | Permit rate > 90% |
|
||||
| Gradual shift | Coverage maintained; permit rate may decrease |
|
||||
| Abrupt shift | Temporary DEFER; recovery within 100 steps |
|
||||
| Adversarial probe | DENY rate increases; alerts generated |
|
||||
| Component failure | Graceful degradation; no unsafe permits |
|
||||
|
||||
### DDC-6.3: Benchmark Requirements
|
||||
|
||||
| Metric | Target | Measurement Method |
|
||||
|--------|--------|-------------------|
|
||||
| Gate latency p50 | < 10ms | Continuous profiling |
|
||||
| Gate latency p99 | < 50ms | Continuous profiling |
|
||||
| False deny rate | < 5% | Simulation with known-safe actions |
|
||||
| Missed unsafe rate | < 0.1% | Simulation with known-unsafe actions |
|
||||
| Coverage maintenance | ≥ 85% | Real distribution shift scenarios |
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Phases
|
||||
|
||||
### Phase 1: Foundation (v0.1)
|
||||
- [ ] E-value and e-process core implementation
|
||||
- [ ] Basic conformal prediction with ACI
|
||||
- [ ] Integration with existing `GateController`
|
||||
- [ ] Simple witness receipts
|
||||
|
||||
### Phase 2: Adaptation (v0.2)
|
||||
- [ ] COP and retrospective adjustment
|
||||
- [ ] Mixture e-values for robustness
|
||||
- [ ] Graph model with conformal-based weights
|
||||
- [ ] Enhanced audit trail
|
||||
|
||||
### Phase 3: Production (v1.0)
|
||||
- [ ] CORE RL-based adaptation
|
||||
- [ ] Learned graph construction
|
||||
- [ ] Cryptographic receipt signing
|
||||
- [ ] Full monitoring and alerting
|
||||
|
||||
---
|
||||
|
||||
## 8. Open Questions for Review
|
||||
|
||||
1. **Graph Model Scope**: Should the action graph include only immediate actions or multi-step lookahead?
|
||||
|
||||
2. **E-Process Null**: Is "action safety" the right null hypothesis, or should we test "policy consistency"?
|
||||
|
||||
3. **Threshold Learning**: Should thresholds be fixed or learned via meta-optimization?
|
||||
|
||||
4. **Human-in-Loop**: How should DEFER decisions be presented to human operators?
|
||||
|
||||
5. **Adversarial Robustness**: How does AVCG perform against adaptive adversaries who observe gate decisions?
|
||||
|
||||
---
|
||||
|
||||
## 9. Sign-Off
|
||||
|
||||
| Role | Name | Date | Signature |
|
||||
|------|------|------|-----------|
|
||||
| Architecture Lead | | | |
|
||||
| Security Lead | | | |
|
||||
| ML Lead | | | |
|
||||
| Engineering Lead | | | |
|
||||
|
||||
---
|
||||
|
||||
## Appendix A: Glossary
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| **E-value** | Nonnegative test statistic with E[e] ≤ 1 under null |
|
||||
| **E-process** | Sequence of e-values forming a nonnegative supermartingale |
|
||||
| **Conformal Prediction** | Distribution-free method for calibrated uncertainty |
|
||||
| **Witness Partition** | Explicit (S, V\S) showing which vertices are separated |
|
||||
| **Anytime-Valid** | Guarantee holds at any stopping time |
|
||||
| **COP** | Conformal Optimistic Prediction |
|
||||
| **CORE** | Conformal Regression via Reinforcement Learning |
|
||||
| **ACI** | Adaptive Conformal Inference |
|
||||
|
||||
## Appendix B: Key Equations
|
||||
|
||||
### E-Value Validity
|
||||
```
|
||||
E_H₀[e] ≤ 1
|
||||
```
|
||||
|
||||
### Anytime-Valid Type I Error
|
||||
```
|
||||
P_H₀(∃t: E_t ≥ 1/α) ≤ α
|
||||
```
|
||||
|
||||
### Conformal Coverage
|
||||
```
|
||||
P(Y_{t+1} ∈ C_t(X_{t+1})) ≥ 1 - α
|
||||
```
|
||||
|
||||
### E-Value Composition
|
||||
```
|
||||
e₁ · e₂ is valid if e₁, e₂ independent
|
||||
```
|
||||
559
vendor/ruvector/crates/ruvector-mincut/docs/adr/ROADMAP-coherence-gate-implementation.md
vendored
Normal file
559
vendor/ruvector/crates/ruvector-mincut/docs/adr/ROADMAP-coherence-gate-implementation.md
vendored
Normal file
@@ -0,0 +1,559 @@
|
||||
# Implementation Roadmap: Anytime-Valid Coherence Gate
|
||||
|
||||
**Version**: 1.0
|
||||
**Date**: 2026-01-17
|
||||
**Related**: ADR-001, DDC-001
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document provides a phased implementation roadmap for the Anytime-Valid Coherence Gate (AVCG), integrating:
|
||||
1. **Dynamic Min-Cut** (existing, enhanced)
|
||||
2. **Online Conformal Prediction** (new)
|
||||
3. **E-Values/E-Processes** (new)
|
||||
|
||||
The implementation is designed for incremental delivery with each phase providing standalone value.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Preparation (Current State Analysis)
|
||||
|
||||
### Existing Infrastructure ✅
|
||||
|
||||
| Component | Location | Status |
|
||||
|-----------|----------|--------|
|
||||
| `SubpolynomialMinCut` | `src/subpolynomial/mod.rs` | Production-ready |
|
||||
| `WitnessTree` | `src/witness/mod.rs` | Production-ready |
|
||||
| `CutCertificate` | `src/certificate/mod.rs` | Production-ready |
|
||||
| `DeterministicLocalKCut` | `src/localkcut/` | Production-ready |
|
||||
| `GateController` | `mincut-gated-transformer/src/gate.rs` | Production-ready |
|
||||
| `GatePacket` | `mincut-gated-transformer/src/packets.rs` | Production-ready |
|
||||
|
||||
### Dependencies to Add
|
||||
|
||||
```toml
|
||||
# Cargo.toml additions for ruvector-mincut
|
||||
[dependencies]
|
||||
# Statistics
|
||||
statrs = "0.17" # Statistical distributions
|
||||
rand = "0.8" # Random number generation
|
||||
rand_distr = "0.4" # Probability distributions
|
||||
|
||||
# Serialization for receipts
|
||||
serde_json = "1.0"
|
||||
bincode = "1.3"
|
||||
blake3 = "1.5" # Fast cryptographic hashing
|
||||
|
||||
# Optional: async support
|
||||
tokio = { version = "1", features = ["sync"], optional = true }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: E-Process Foundation
|
||||
|
||||
**Goal**: Implement core e-value and e-process infrastructure.
|
||||
|
||||
### Task 1.1: E-Value Module
|
||||
|
||||
Create `src/eprocess/evalue.rs`:
|
||||
|
||||
```rust
|
||||
/// Core e-value type with validity guarantees
|
||||
pub struct EValue {
|
||||
value: f64,
|
||||
/// Null hypothesis under which E[e] ≤ 1
|
||||
null: NullHypothesis,
|
||||
/// Computation timestamp
|
||||
timestamp: u64,
|
||||
}
|
||||
|
||||
/// Supported null hypotheses
|
||||
pub enum NullHypothesis {
|
||||
/// P(unsafe outcome) ≤ p0
|
||||
ActionSafety { p0: f64 },
|
||||
/// Current state ~ reference distribution
|
||||
StateStability { reference: DistributionId },
|
||||
/// Policy matches reference
|
||||
PolicyConsistency { reference: PolicyId },
|
||||
}
|
||||
|
||||
impl EValue {
|
||||
/// Create from likelihood ratio
|
||||
pub fn from_likelihood_ratio(
|
||||
likelihood_h1: f64,
|
||||
likelihood_h0: f64,
|
||||
) -> Self;
|
||||
|
||||
/// Create mixture e-value for robustness
|
||||
pub fn from_mixture(
|
||||
components: &[EValue],
|
||||
weights: &[f64],
|
||||
) -> Self;
|
||||
|
||||
/// Verify E[e] ≤ 1 property empirically
|
||||
pub fn verify_validity(&self, samples: &[f64]) -> bool;
|
||||
}
|
||||
```
|
||||
|
||||
### Task 1.2: E-Process Module
|
||||
|
||||
Create `src/eprocess/process.rs`:
|
||||
|
||||
```rust
|
||||
/// E-process for continuous monitoring
|
||||
pub struct EProcess {
|
||||
/// Current accumulated value
|
||||
current: f64,
|
||||
/// History for audit
|
||||
history: Vec<EValue>,
|
||||
/// Update rule
|
||||
update_rule: UpdateRule,
|
||||
}
|
||||
|
||||
pub enum UpdateRule {
|
||||
/// E_t = Π e_i (aggressive)
|
||||
Product,
|
||||
/// E_t = (1/t) Σ e_i (conservative)
|
||||
Average,
|
||||
/// E_t = λe_t + (1-λ)E_{t-1}
|
||||
ExponentialMoving { lambda: f64 },
|
||||
/// E_t = Σ w_j E_t^{(j)}
|
||||
Mixture { weights: Vec<f64> },
|
||||
}
|
||||
|
||||
impl EProcess {
|
||||
pub fn new(rule: UpdateRule) -> Self;
|
||||
pub fn update(&mut self, e: EValue);
|
||||
pub fn current_value(&self) -> f64;
|
||||
|
||||
/// Check stopping condition
|
||||
pub fn should_stop(&self, threshold: f64) -> bool;
|
||||
|
||||
/// Export for audit
|
||||
pub fn to_evidence_receipt(&self) -> EvidenceReceipt;
|
||||
}
|
||||
```
|
||||
|
||||
### Task 1.3: Stopping Rules
|
||||
|
||||
Create `src/eprocess/stopping.rs`:
|
||||
|
||||
```rust
|
||||
/// Anytime-valid stopping rule
|
||||
pub struct StoppingRule {
|
||||
/// Threshold for rejection
|
||||
reject_threshold: f64, // typically 1/α
|
||||
/// Threshold for acceptance (optional)
|
||||
accept_threshold: Option<f64>,
|
||||
}
|
||||
|
||||
impl StoppingRule {
|
||||
/// Check if we can stop now
|
||||
pub fn can_stop(&self, e_process: &EProcess) -> StoppingDecision;
|
||||
|
||||
/// Get confidence at current stopping time
|
||||
pub fn confidence_at_stop(&self, e_process: &EProcess) -> f64;
|
||||
}
|
||||
|
||||
pub enum StoppingDecision {
|
||||
/// Continue accumulating evidence
|
||||
Continue,
|
||||
/// Reject null (evidence of incoherence)
|
||||
Reject { confidence: f64 },
|
||||
/// Accept null (evidence of coherence)
|
||||
Accept { confidence: f64 },
|
||||
}
|
||||
```
|
||||
|
||||
### Deliverables Phase 1
|
||||
- [ ] `src/eprocess/mod.rs` - module organization
|
||||
- [ ] `src/eprocess/evalue.rs` - e-value implementation
|
||||
- [ ] `src/eprocess/process.rs` - e-process implementation
|
||||
- [ ] `src/eprocess/stopping.rs` - stopping rules
|
||||
- [ ] `src/eprocess/mixture.rs` - mixture e-values
|
||||
- [ ] Unit tests with ≥95% coverage
|
||||
- [ ] Integration with `CutCertificate`
|
||||
|
||||
### Acceptance Criteria Phase 1
|
||||
- [ ] E[e] ≤ 1 verified for all implemented e-value types
|
||||
- [ ] E-process maintains supermartingale property
|
||||
- [ ] Stopping rule provides valid Type I error control
|
||||
- [ ] Computation time < 1ms for single e-value
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Conformal Prediction
|
||||
|
||||
**Goal**: Implement online conformal prediction with shift adaptation.
|
||||
|
||||
### Task 2.1: Prediction Set Core
|
||||
|
||||
Create `src/conformal/prediction_set.rs`:
|
||||
|
||||
```rust
|
||||
/// Conformal prediction set
|
||||
pub struct PredictionSet<T> {
|
||||
/// Elements in the set
|
||||
elements: Vec<T>,
|
||||
/// Coverage target
|
||||
coverage: f64,
|
||||
/// Non-conformity scores
|
||||
scores: Vec<f64>,
|
||||
}
|
||||
|
||||
impl<T> PredictionSet<T> {
|
||||
/// Check if outcome is in set
|
||||
pub fn contains(&self, outcome: &T) -> bool;
|
||||
|
||||
/// Get set size (measure of uncertainty)
|
||||
pub fn size(&self) -> usize;
|
||||
|
||||
/// Get normalized uncertainty measure
|
||||
pub fn uncertainty(&self) -> f64;
|
||||
}
|
||||
```
|
||||
|
||||
### Task 2.2: Non-Conformity Scores
|
||||
|
||||
Create `src/conformal/scores.rs`:
|
||||
|
||||
```rust
|
||||
/// Non-conformity score function
|
||||
pub trait NonConformityScore {
|
||||
type Input;
|
||||
type Output;
|
||||
|
||||
fn score(&self, input: &Self::Input, output: &Self::Output) -> f64;
|
||||
}
|
||||
|
||||
/// Absolute residual score
|
||||
pub struct AbsoluteResidual<P: Predictor> {
|
||||
predictor: P,
|
||||
}
|
||||
|
||||
/// Normalized residual score
|
||||
pub struct NormalizedResidual<P: Predictor + UncertaintyEstimator> {
|
||||
predictor: P,
|
||||
}
|
||||
|
||||
/// Conformalized Quantile Regression (CQR)
|
||||
pub struct CQRScore<Q: QuantilePredictor> {
|
||||
quantile_predictor: Q,
|
||||
}
|
||||
```
|
||||
|
||||
### Task 2.3: Online Conformal with Adaptation
|
||||
|
||||
Create `src/conformal/online.rs`:
|
||||
|
||||
```rust
|
||||
/// Online conformal predictor with shift adaptation
|
||||
pub struct OnlineConformal<S: NonConformityScore> {
|
||||
score_fn: S,
|
||||
/// Calibration buffer
|
||||
calibration: RingBuffer<f64>,
|
||||
/// Current quantile
|
||||
quantile: f64,
|
||||
/// Adaptation method
|
||||
adaptation: AdaptationMethod,
|
||||
}
|
||||
|
||||
pub enum AdaptationMethod {
|
||||
/// Adaptive Conformal Inference
|
||||
ACI { learning_rate: f64 },
|
||||
/// Retrospective adjustment
|
||||
Retrospective { window: usize },
|
||||
/// Conformal Optimistic Prediction
|
||||
COP { cdf_estimator: Box<dyn CDFEstimator> },
|
||||
}
|
||||
|
||||
impl<S: NonConformityScore> OnlineConformal<S> {
|
||||
/// Generate prediction set
|
||||
pub fn predict(&self, input: &S::Input) -> PredictionSet<S::Output>;
|
||||
|
||||
/// Update with observed outcome
|
||||
pub fn update(&mut self, input: &S::Input, outcome: &S::Output);
|
||||
|
||||
/// Get current coverage estimate
|
||||
pub fn coverage_estimate(&self) -> f64;
|
||||
}
|
||||
```
|
||||
|
||||
### Task 2.4: CORE RL-Based Adaptation
|
||||
|
||||
Create `src/conformal/core.rs`:
|
||||
|
||||
```rust
|
||||
/// CORE: RL-based conformal adaptation
|
||||
pub struct COREConformal<S: NonConformityScore> {
|
||||
base: OnlineConformal<S>,
|
||||
/// RL agent for quantile adjustment
|
||||
agent: QuantileAgent,
|
||||
/// Coverage as reward signal
|
||||
coverage_target: f64,
|
||||
}
|
||||
|
||||
/// Simple TD-learning agent for quantile adjustment
|
||||
struct QuantileAgent {
|
||||
q_value: f64,
|
||||
learning_rate: f64,
|
||||
discount: f64,
|
||||
}
|
||||
|
||||
impl<S: NonConformityScore> COREConformal<S> {
|
||||
/// Predict with RL-adjusted quantile
|
||||
pub fn predict(&self, input: &S::Input) -> PredictionSet<S::Output>;
|
||||
|
||||
/// Update agent and base conformal
|
||||
pub fn update(&mut self, input: &S::Input, outcome: &S::Output, covered: bool);
|
||||
}
|
||||
```
|
||||
|
||||
### Deliverables Phase 2
|
||||
- [ ] `src/conformal/mod.rs` - module organization
|
||||
- [ ] `src/conformal/prediction_set.rs` - prediction set types
|
||||
- [ ] `src/conformal/scores.rs` - non-conformity scores
|
||||
- [ ] `src/conformal/online.rs` - online conformal with ACI
|
||||
- [ ] `src/conformal/retrospective.rs` - retrospective adjustment
|
||||
- [ ] `src/conformal/cop.rs` - Conformal Optimistic Prediction
|
||||
- [ ] `src/conformal/core.rs` - RL-based adaptation
|
||||
- [ ] Unit tests with ≥90% coverage
|
||||
|
||||
### Acceptance Criteria Phase 2
|
||||
- [ ] Marginal coverage ≥ 1 - α on exchangeable data
|
||||
- [ ] Coverage maintained under gradual shift (δ < 0.1/step)
|
||||
- [ ] Recovery within 100 steps after abrupt shift
|
||||
- [ ] Prediction latency < 10ms
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Gate Integration
|
||||
|
||||
**Goal**: Integrate all components into unified gate controller.
|
||||
|
||||
### Task 3.1: Anytime Gate Policy
|
||||
|
||||
Create `src/anytime_gate/policy.rs`:
|
||||
|
||||
```rust
|
||||
/// Policy for anytime-valid gate
|
||||
pub struct AnytimeGatePolicy {
|
||||
/// E-process thresholds
|
||||
pub e_deny_threshold: f64, // τ_deny
|
||||
pub e_permit_threshold: f64, // τ_permit
|
||||
|
||||
/// Conformal thresholds
|
||||
pub uncertainty_threshold: f64, // θ_uncertainty
|
||||
pub confidence_threshold: f64, // θ_confidence
|
||||
|
||||
/// Min-cut thresholds (from existing GatePolicy)
|
||||
pub lambda_min: u32,
|
||||
pub boundary_max: u16,
|
||||
|
||||
/// Adaptation settings
|
||||
pub adaptive_thresholds: bool,
|
||||
pub threshold_learning_rate: f64,
|
||||
}
|
||||
```
|
||||
|
||||
### Task 3.2: Unified Gate Controller
|
||||
|
||||
Create `src/anytime_gate/controller.rs`:
|
||||
|
||||
```rust
|
||||
/// Unified anytime-valid coherence gate
|
||||
pub struct AnytimeGateController<S: NonConformityScore> {
|
||||
/// Existing min-cut infrastructure
|
||||
mincut: SubpolynomialMinCut,
|
||||
|
||||
/// Conformal predictor
|
||||
conformal: OnlineConformal<S>,
|
||||
|
||||
/// E-process for evidence
|
||||
e_process: EProcess,
|
||||
|
||||
/// Policy
|
||||
policy: AnytimeGatePolicy,
|
||||
}
|
||||
|
||||
impl<S: NonConformityScore> AnytimeGateController<S> {
|
||||
/// Evaluate gate for action
|
||||
pub fn evaluate(&mut self, action: &Action, context: &Context) -> GateResult;
|
||||
|
||||
/// Update after observing outcome
|
||||
pub fn update(&mut self, action: &Action, outcome: &Outcome);
|
||||
|
||||
/// Generate witness receipt
|
||||
pub fn receipt(&self, decision: &GateDecision) -> WitnessReceipt;
|
||||
}
|
||||
|
||||
pub struct GateResult {
|
||||
pub decision: GateDecision,
|
||||
|
||||
// From min-cut
|
||||
pub cut_value: f64,
|
||||
pub witness_partition: Option<WitnessPartition>,
|
||||
|
||||
// From conformal
|
||||
pub prediction_set_size: f64,
|
||||
pub uncertainty: f64,
|
||||
|
||||
// From e-process
|
||||
pub e_value: f64,
|
||||
pub evidence_sufficient: bool,
|
||||
}
|
||||
```
|
||||
|
||||
### Task 3.3: Witness Receipt
|
||||
|
||||
Create `src/anytime_gate/receipt.rs`:
|
||||
|
||||
```rust
|
||||
/// Cryptographically sealed witness receipt
|
||||
#[derive(Serialize, Deserialize)]
|
||||
pub struct WitnessReceipt {
|
||||
/// Receipt metadata
|
||||
pub id: Uuid,
|
||||
pub timestamp: u64,
|
||||
pub action_id: ActionId,
|
||||
pub decision: GateDecision,
|
||||
|
||||
/// Structural witness (from min-cut)
|
||||
pub structural: StructuralWitness,
|
||||
|
||||
/// Predictive witness (from conformal)
|
||||
pub predictive: PredictiveWitness,
|
||||
|
||||
/// Evidential witness (from e-process)
|
||||
pub evidential: EvidentialWitness,
|
||||
|
||||
/// Cryptographic seal
|
||||
pub hash: [u8; 32],
|
||||
pub signature: Option<[u8; 64]>,
|
||||
}
|
||||
|
||||
#[derive(Serialize, Deserialize)]
|
||||
pub struct StructuralWitness {
|
||||
pub cut_value: f64,
|
||||
pub partition_hash: [u8; 32],
|
||||
pub critical_edge_count: usize,
|
||||
}
|
||||
|
||||
#[derive(Serialize, Deserialize)]
|
||||
pub struct PredictiveWitness {
|
||||
pub prediction_set_size: usize,
|
||||
pub coverage_target: f64,
|
||||
pub adaptation_rate: f64,
|
||||
}
|
||||
|
||||
#[derive(Serialize, Deserialize)]
|
||||
pub struct EvidentialWitness {
|
||||
pub e_value: f64,
|
||||
pub e_process_cumulative: f64,
|
||||
pub null_hypothesis: String,
|
||||
pub stopping_valid: bool,
|
||||
}
|
||||
|
||||
impl WitnessReceipt {
|
||||
pub fn seal(&mut self) {
|
||||
self.hash = blake3::hash(&self.to_bytes()).into();
|
||||
}
|
||||
|
||||
pub fn verify(&self) -> bool {
|
||||
self.hash == blake3::hash(&self.to_bytes_without_hash()).into()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Deliverables Phase 3
|
||||
- [ ] `src/anytime_gate/mod.rs` - module organization
|
||||
- [ ] `src/anytime_gate/policy.rs` - gate policy
|
||||
- [ ] `src/anytime_gate/controller.rs` - unified controller
|
||||
- [ ] `src/anytime_gate/decision.rs` - decision types
|
||||
- [ ] `src/anytime_gate/receipt.rs` - witness receipts
|
||||
- [ ] Integration tests with full pipeline
|
||||
- [ ] Benchmarks for latency validation
|
||||
|
||||
### Acceptance Criteria Phase 3
|
||||
- [ ] Gate latency p99 < 50ms
|
||||
- [ ] All three signals integrated correctly
|
||||
- [ ] Witness receipts pass verification
|
||||
- [ ] Graceful degradation on component failure
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Production Hardening
|
||||
|
||||
**Goal**: Production-ready implementation with monitoring and optimization.
|
||||
|
||||
### Task 4.1: Performance Optimization
|
||||
- [ ] SIMD-optimized e-value computation
|
||||
- [ ] Lazy evaluation for conformal sets
|
||||
- [ ] Batched graph updates for min-cut
|
||||
- [ ] Memory-mapped receipt storage
|
||||
|
||||
### Task 4.2: Monitoring & Alerting
|
||||
- [ ] Prometheus metrics for gate decisions
|
||||
- [ ] Coverage drift detection
|
||||
- [ ] E-process anomaly alerts
|
||||
- [ ] Latency histogram tracking
|
||||
|
||||
### Task 4.3: Operational Tooling
|
||||
- [ ] Receipt query API
|
||||
- [ ] Threshold tuning dashboard
|
||||
- [ ] A/B testing framework for policy comparison
|
||||
- [ ] Incident replay from receipts
|
||||
|
||||
### Task 4.4: Documentation
|
||||
- [ ] API documentation
|
||||
- [ ] Operator runbook
|
||||
- [ ] Threshold tuning guide
|
||||
- [ ] Troubleshooting guide
|
||||
|
||||
---
|
||||
|
||||
## Timeline Summary
|
||||
|
||||
| Phase | Duration | Dependencies | Deliverable |
|
||||
|-------|----------|--------------|-------------|
|
||||
| Phase 0 | Complete | - | Requirements analysis |
|
||||
| Phase 1 | 2 weeks | None | E-process module |
|
||||
| Phase 2 | 3 weeks | Phase 1 | Conformal module |
|
||||
| Phase 3 | 2 weeks | Phase 1, 2 | Unified gate |
|
||||
| Phase 4 | 2 weeks | Phase 3 | Production hardening |
|
||||
|
||||
**Total estimated effort**: 9 weeks
|
||||
|
||||
---
|
||||
|
||||
## Risk Register
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
| E-value power too low | Medium | High | Mixture e-values; tuned alternatives |
|
||||
| Conformal sets too large | Medium | Medium | COP for tighter sets; better base predictor |
|
||||
| Latency exceeds budget | Low | High | Early profiling; lazy evaluation |
|
||||
| Integration complexity | Medium | Medium | Phased delivery; isolated modules |
|
||||
| Threshold tuning difficulty | High | Medium | Adaptive thresholds; meta-learning |
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Target | Measurement |
|
||||
|--------|--------|-------------|
|
||||
| False deny rate | < 5% | Simulation |
|
||||
| Missed unsafe rate | < 0.1% | Simulation |
|
||||
| Gate latency p99 | < 50ms | Production |
|
||||
| Coverage maintenance | ≥ 85% | Production |
|
||||
| Receipt verification pass | 100% | Audit |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
1. El-Hayek, Henzinger, Li. arXiv:2512.13105 (Dec 2025)
|
||||
2. Online Conformal with Retrospective. arXiv:2511.04275 (Nov 2025)
|
||||
3. Ramdas, Wang. "Hypothesis Testing with E-values" (2025)
|
||||
4. ICML 2025 Tutorial on SAVI
|
||||
5. Distribution-informed Conformal (COP). arXiv:2512.07770 (Dec 2025)
|
||||
208
vendor/ruvector/crates/ruvector-mincut/docs/bounded_testing_summary.md
vendored
Normal file
208
vendor/ruvector/crates/ruvector-mincut/docs/bounded_testing_summary.md
vendored
Normal file
@@ -0,0 +1,208 @@
|
||||
# Bounded-Range Dynamic Minimum Cut - Testing Summary
|
||||
|
||||
## Overview
|
||||
|
||||
Created comprehensive integration tests and benchmarks for the bounded-range dynamic minimum cut system, implementing the wrapper algorithm from the December 2024 paper.
|
||||
|
||||
## Files Created
|
||||
|
||||
### Integration Tests
|
||||
**File**: `/home/user/ruvector/crates/ruvector-mincut/tests/bounded_integration.rs`
|
||||
|
||||
16 comprehensive integration tests covering:
|
||||
|
||||
1. **Graph Topologies**
|
||||
- Path graphs (P_n) - min cut = 1
|
||||
- Cycle graphs (C_n) - min cut = 2
|
||||
- Complete graphs (K_n) - min cut = n-1
|
||||
- Grid graphs - min cut = 2 (corner vertices)
|
||||
- Star graphs - min cut = 1
|
||||
- Bridge graphs (dumbbell) - min cut = 1
|
||||
|
||||
2. **Dynamic Operations**
|
||||
- Edge insertions
|
||||
- Edge deletions
|
||||
- Incremental updates (path → cycle → path)
|
||||
- Buffered updates before query
|
||||
|
||||
3. **Correctness Properties**
|
||||
- Disconnected graphs (min cut = 0)
|
||||
- Empty graphs
|
||||
- Single edges
|
||||
- Deterministic results
|
||||
- Multiple query consistency
|
||||
|
||||
4. **Stress Testing**
|
||||
- 1000 random edge insertions
|
||||
- Large graphs (100 vertices)
|
||||
- Lazy instance instantiation
|
||||
|
||||
### Benchmarks
|
||||
**File**: `/home/user/ruvector/crates/ruvector-mincut/benches/bounded_bench.rs`
|
||||
|
||||
Comprehensive performance benchmarks:
|
||||
|
||||
1. **Basic Operations**
|
||||
- `benchmark_insert_edge` - Insertion throughput at various graph sizes (100-5000 vertices)
|
||||
- `benchmark_delete_edge` - Deletion throughput
|
||||
- `benchmark_query` - Query latency
|
||||
- `benchmark_query_after_updates` - Query performance with buffered updates (10-500 updates)
|
||||
|
||||
2. **Graph Topologies**
|
||||
- Path graphs
|
||||
- Cycle graphs
|
||||
- Grid graphs (22×22 = 484 vertices)
|
||||
- Complete graphs (30 vertices)
|
||||
|
||||
3. **Workload Patterns**
|
||||
- `benchmark_mixed_workload` - Realistic mix: 70% queries, 20% inserts, 10% deletes
|
||||
- `benchmark_lazy_instantiation` - First query vs subsequent queries
|
||||
|
||||
4. **Performance Scaling**
|
||||
- Measures throughput using Criterion's `Throughput::Elements`
|
||||
- Tests multiple graph sizes to verify subpolynomial scaling
|
||||
- Isolates setup from measurement using `iter_batched`
|
||||
|
||||
## Key Bugs Fixed
|
||||
|
||||
### 1. Iterator Issue in LocalKCut
|
||||
**File**: `src/localkcut/paper_impl.rs`
|
||||
|
||||
Fixed missing `.into_iter()` calls when mapping over `graph.neighbors()` results.
|
||||
|
||||
```rust
|
||||
// Before (broken)
|
||||
let neighbors = graph.neighbors(v).map(|(neighbor, _)| neighbor).collect();
|
||||
|
||||
// After (fixed)
|
||||
let neighbors = graph.neighbors(v).into_iter().map(|(neighbor, _)| neighbor).collect();
|
||||
```
|
||||
|
||||
### 2. Stub Instance Overflow
|
||||
**File**: `src/instance/stub.rs`
|
||||
|
||||
Added check to prevent overflow when computing `1u64 << n` for large graphs:
|
||||
|
||||
```rust
|
||||
// Stub instance only works for small graphs (n < 20)
|
||||
if n >= 20 {
|
||||
return None; // Triggers AboveRange
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Wrapper Instance Initialization
|
||||
**File**: `src/instance/stub.rs`, `src/wrapper/mod.rs`
|
||||
|
||||
Distinguished between two initialization modes:
|
||||
- `new()` - Copies initial graph state (for direct testing)
|
||||
- `init()` - Starts empty (for wrapper use, which applies edges via `apply_inserts`)
|
||||
|
||||
### 4. Wrapper AboveRange Handling
|
||||
**File**: `src/wrapper/mod.rs`
|
||||
|
||||
Fixed logic to continue searching instances instead of stopping on first `AboveRange`:
|
||||
|
||||
```rust
|
||||
// Before (broken)
|
||||
InstanceResult::AboveRange => {
|
||||
break; // Would stop immediately!
|
||||
}
|
||||
|
||||
// After (fixed)
|
||||
InstanceResult::AboveRange => {
|
||||
continue; // Try next instance with larger range
|
||||
}
|
||||
```
|
||||
|
||||
### 5. New Instance State Initialization (Critical Fix!)
|
||||
**File**: `src/wrapper/mod.rs`
|
||||
|
||||
Fixed bug where new instances created on subsequent queries didn't receive historical edges:
|
||||
|
||||
```rust
|
||||
if is_new_instance {
|
||||
// New instance: apply ALL edges from the current graph state
|
||||
let all_edges: Vec<_> = self.graph.edges()
|
||||
.iter()
|
||||
.map(|e| (e.id, e.source, e.target))
|
||||
.collect();
|
||||
instance.apply_inserts(&all_edges);
|
||||
} else {
|
||||
// Existing instance: apply only new updates since last query
|
||||
let inserts: Vec<_> = self.pending_inserts
|
||||
.iter()
|
||||
.filter(|u| u.time > last_time)
|
||||
.map(|u| (u.edge_id, u.u, u.v))
|
||||
.collect();
|
||||
instance.apply_inserts(&inserts);
|
||||
}
|
||||
```
|
||||
|
||||
## Test Results
|
||||
|
||||
### Integration Tests
|
||||
```
|
||||
test result: ok. 16 passed; 0 failed
|
||||
```
|
||||
|
||||
All tests pass, covering:
|
||||
- Graph topologies (path, cycle, complete, grid, star, bridge)
|
||||
- Dynamic updates (insertions, deletions, incremental)
|
||||
- Edge cases (empty, disconnected, single edge)
|
||||
- Stress testing (1000 random edges, 100 vertices)
|
||||
- Correctness (determinism, consistency)
|
||||
|
||||
### Benchmarks
|
||||
```
|
||||
Finished `bench` profile [optimized + debuginfo]
|
||||
Executable: bounded_bench
|
||||
```
|
||||
|
||||
Benchmarks compile successfully and ready to run with:
|
||||
```bash
|
||||
cargo bench --bench bounded_bench --package ruvector-mincut
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
Based on test observations:
|
||||
|
||||
1. **Instance Creation**: Lazy instantiation - instances only created when needed
|
||||
2. **Query Time**: O(log n) instances checked in worst case
|
||||
3. **Update Time**: Incremental - only new updates applied to existing instances
|
||||
4. **Memory**: Grows with graph size + O(log n) instances
|
||||
|
||||
Typical instance counts observed:
|
||||
- Path graph (10 vertices, min cut 1): 1 instance
|
||||
- Cycle graph (5 vertices, min cut 2): 4 instances
|
||||
- Grid graph (9 vertices, min cut 2): Similar pattern
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
# Run all integration tests
|
||||
cargo test --test bounded_integration --package ruvector-mincut
|
||||
|
||||
# Run with output
|
||||
cargo test --test bounded_integration --package ruvector-mincut -- --nocapture
|
||||
|
||||
# Run specific test
|
||||
cargo test --test bounded_integration test_cycle_graph_integration --package ruvector-mincut
|
||||
|
||||
# Run benchmarks
|
||||
cargo bench --bench bounded_bench --package ruvector-mincut
|
||||
```
|
||||
|
||||
## Future Improvements
|
||||
|
||||
1. **Replace StubInstance**: Current brute-force O(2^n) implementation should be replaced with real LocalKCut algorithm for n > 20
|
||||
2. **Deletions**: Test coverage for deletion-heavy workloads
|
||||
3. **Weighted Graphs**: More extensive testing with non-unit edge weights
|
||||
4. **Concurrency**: Add tests for concurrent queries (wrapper uses Arc internally)
|
||||
5. **Memory Bounds**: Add tests verifying memory usage stays bounded
|
||||
|
||||
## References
|
||||
|
||||
- Paper: "Subpolynomial-time Dynamic Minimum Cut" (December 2024, arxiv:2512.13105)
|
||||
- Implementation follows wrapper algorithm from Section 3
|
||||
- Uses geometric range factor 1.2 with O(log n) instances
|
||||
649
vendor/ruvector/crates/ruvector-mincut/docs/guide/01-getting-started.md
vendored
Normal file
649
vendor/ruvector/crates/ruvector-mincut/docs/guide/01-getting-started.md
vendored
Normal file
@@ -0,0 +1,649 @@
|
||||
# Getting Started with RuVector MinCut
|
||||
|
||||
Welcome to RuVector MinCut! This guide will help you understand minimum cuts and start using the library in your Rust projects.
|
||||
|
||||
---
|
||||
|
||||
## 1. What is Minimum Cut?
|
||||
|
||||
### The Simple Explanation
|
||||
|
||||
Imagine you have a network of roads connecting different cities. The **minimum cut** answers this question:
|
||||
|
||||
> **"What's the smallest number of roads I need to close to completely separate the network into two parts?"**
|
||||
|
||||
Think of it like finding the **weakest links in a chain** — the places where your network is most vulnerable to breaking apart.
|
||||
|
||||
### Real-World Analogies
|
||||
|
||||
| Scenario | What You Have | What Min-Cut Finds |
|
||||
|----------|---------------|-------------------|
|
||||
| **Road Network** | Cities connected by roads | Fewest roads to block to isolate a city |
|
||||
| **Social Network** | People connected by friendships | Weakest link between two communities |
|
||||
| **Computer Network** | Servers connected by cables | Most vulnerable connections if attacked |
|
||||
| **Water Pipes** | Houses connected by pipes | Minimum pipes to shut off to stop water flow |
|
||||
| **Supply Chain** | Factories connected by routes | Critical dependencies that could break the chain |
|
||||
|
||||
### Visual Example
|
||||
|
||||
Here's what a minimum cut looks like in a simple graph:
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Original Graph"
|
||||
A((A)) ---|1| B((B))
|
||||
B ---|1| C((C))
|
||||
C ---|1| D((D))
|
||||
A ---|1| D((D))
|
||||
B ---|1| D((D))
|
||||
end
|
||||
|
||||
subgraph "After Minimum Cut (value = 2)"
|
||||
A1((A)) -.x.- B1((B))
|
||||
B1((B)) ---|1| C1((C))
|
||||
C1((C)) ---|1| D1((D))
|
||||
A1((A)) -.x.- D1((D))
|
||||
B1 ---|1| D1
|
||||
end
|
||||
|
||||
style A1 fill:#ffcccc
|
||||
style A fill:#ffcccc
|
||||
style B fill:#ccccff
|
||||
style C fill:#ccccff
|
||||
style D fill:#ccccff
|
||||
style B1 fill:#ccccff
|
||||
style C1 fill:#ccccff
|
||||
style D1 fill:#ccccff
|
||||
```
|
||||
|
||||
**Legend:**
|
||||
- **Solid lines** (—): Edges that remain
|
||||
- **Crossed lines** (-.x.-): Edges in the minimum cut (removed)
|
||||
- **Red nodes**: One side of the partition (set S)
|
||||
- **Blue nodes**: Other side of the partition (set T)
|
||||
|
||||
The minimum cut value is **2** because we need to remove 2 edges to disconnect node A from the rest.
|
||||
|
||||
### Key Terminology for Beginners
|
||||
|
||||
| Term | Simple Explanation | Example |
|
||||
|------|-------------------|---------|
|
||||
| **Vertex** (or Node) | A point in the network | A city, a person, a server |
|
||||
| **Edge** | A connection between two vertices | A road, a friendship, a cable |
|
||||
| **Weight** | The "strength" or "capacity" of an edge | Road width, friendship closeness |
|
||||
| **Cut** | A set of edges that, when removed, splits the graph | Roads to close to isolate a city |
|
||||
| **Partition** | The two groups created after a cut | Cities on each side of the divide |
|
||||
| **Cut Value** | Sum of weights of edges in the cut | Total capacity of removed edges |
|
||||
|
||||
### Why Is This Useful?
|
||||
|
||||
- **Find Vulnerabilities**: Identify critical infrastructure that could fail
|
||||
- **Optimize Networks**: Understand where to strengthen connections
|
||||
- **Detect Communities**: Find natural groupings in social networks
|
||||
- **Image Segmentation**: Separate objects from backgrounds in photos
|
||||
- **Load Balancing**: Divide work efficiently across systems
|
||||
|
||||
---
|
||||
|
||||
## 2. Installation
|
||||
|
||||
### Adding to Your Project
|
||||
|
||||
The easiest way to add RuVector MinCut to your project:
|
||||
|
||||
```bash
|
||||
cargo add ruvector-mincut
|
||||
```
|
||||
|
||||
Or manually add to your `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
ruvector-mincut = "0.2"
|
||||
```
|
||||
|
||||
### Understanding Feature Flags
|
||||
|
||||
RuVector MinCut has several optional features you can enable based on your needs:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
ruvector-mincut = { version = "0.2", features = ["monitoring", "simd"] }
|
||||
```
|
||||
|
||||
#### Available Features
|
||||
|
||||
| Feature | Default | What It Does | When to Use |
|
||||
|---------|---------|--------------|-------------|
|
||||
| **`exact`** | ✅ Yes | Exact minimum cut algorithm | When you need guaranteed correct results |
|
||||
| **`approximate`** | ✅ Yes | Fast (1+ε)-approximate algorithm | When speed matters more than perfect accuracy |
|
||||
| **`monitoring`** | ❌ No | Real-time event notifications | When you need alerts for cut changes |
|
||||
| **`integration`** | ❌ No | GraphDB integration with ruvector-graph | When working with vector databases |
|
||||
| **`simd`** | ❌ No | SIMD vector optimizations | For faster processing on modern CPUs |
|
||||
| **`wasm`** | ❌ No | WebAssembly compatibility | For browser or edge deployment |
|
||||
| **`agentic`** | ❌ No | 256-core parallel execution | For agentic chip deployment |
|
||||
|
||||
#### Common Configurations
|
||||
|
||||
```toml
|
||||
# Default: exact + approximate algorithms
|
||||
[dependencies]
|
||||
ruvector-mincut = "0.2"
|
||||
|
||||
# With real-time monitoring
|
||||
[dependencies]
|
||||
ruvector-mincut = { version = "0.2", features = ["monitoring"] }
|
||||
|
||||
# Maximum performance
|
||||
[dependencies]
|
||||
ruvector-mincut = { version = "0.2", features = ["simd"] }
|
||||
|
||||
# Everything enabled
|
||||
[dependencies]
|
||||
ruvector-mincut = { version = "0.2", features = ["full"] }
|
||||
```
|
||||
|
||||
### Quick Feature Decision Guide
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start[Which features do I need?] --> NeedAlerts{Need real-time<br/>alerts?}
|
||||
NeedAlerts -->|Yes| AddMonitoring[Add 'monitoring']
|
||||
NeedAlerts -->|No| CheckSpeed{Need maximum<br/>speed?}
|
||||
|
||||
AddMonitoring --> CheckSpeed
|
||||
|
||||
CheckSpeed -->|Yes| AddSIMD[Add 'simd']
|
||||
CheckSpeed -->|No| CheckWasm{Deploying to<br/>browser/edge?}
|
||||
|
||||
AddSIMD --> CheckWasm
|
||||
|
||||
CheckWasm -->|Yes| AddWasm[Add 'wasm']
|
||||
CheckWasm -->|No| Done[Use default features]
|
||||
|
||||
AddWasm --> Done
|
||||
|
||||
style Start fill:#e1f5ff
|
||||
style Done fill:#c8e6c9
|
||||
style AddMonitoring fill:#fff9c4
|
||||
style AddSIMD fill:#fff9c4
|
||||
style AddWasm fill:#fff9c4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Your First Min-Cut
|
||||
|
||||
Let's create a simple program that finds the minimum cut in a triangle graph.
|
||||
|
||||
### Complete Working Example
|
||||
|
||||
Create a new file `examples/my_first_mincut.rs`:
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::{MinCutBuilder, DynamicMinCut};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
println!("🔷 Finding Minimum Cut in a Triangle\n");
|
||||
|
||||
// Step 1: Create a triangle graph
|
||||
// 1 ------- 2
|
||||
// \ /
|
||||
// \ /
|
||||
// \ /
|
||||
// 3
|
||||
//
|
||||
// Each edge has weight 1.0
|
||||
let mut mincut = MinCutBuilder::new()
|
||||
.exact() // Use exact algorithm for guaranteed correct results
|
||||
.with_edges(vec![
|
||||
(1, 2, 1.0), // Edge from vertex 1 to vertex 2, weight 1.0
|
||||
(2, 3, 1.0), // Edge from vertex 2 to vertex 3, weight 1.0
|
||||
(3, 1, 1.0), // Edge from vertex 3 to vertex 1, weight 1.0
|
||||
])
|
||||
.build()?;
|
||||
|
||||
// Step 2: Query the minimum cut value
|
||||
let cut_value = mincut.min_cut_value();
|
||||
println!("Minimum cut value: {}", cut_value);
|
||||
println!("→ We need to remove {} edge(s) to disconnect the graph\n", cut_value);
|
||||
|
||||
// Step 3: Get the partition (which vertices are on each side?)
|
||||
let (side_s, side_t) = mincut.partition();
|
||||
println!("Partition:");
|
||||
println!(" Side S (red): {:?}", side_s);
|
||||
println!(" Side T (blue): {:?}", side_t);
|
||||
println!("→ These two groups are separated by the cut\n");
|
||||
|
||||
// Step 4: Get the actual edges in the cut
|
||||
let cut_edges = mincut.cut_edges();
|
||||
println!("Edges in the minimum cut:");
|
||||
for (u, v, weight) in &cut_edges {
|
||||
println!(" {} ←→ {} (weight: {})", u, v, weight);
|
||||
}
|
||||
println!("→ These edges must be removed to separate the graph\n");
|
||||
|
||||
// Step 5: Make the graph dynamic - add a new edge
|
||||
println!("📍 Adding edge 3 → 4 (weight 2.0)...");
|
||||
let new_cut = mincut.insert_edge(3, 4, 2.0)?;
|
||||
println!("New minimum cut value: {}", new_cut);
|
||||
println!("→ Adding a leaf node increased connectivity\n");
|
||||
|
||||
// Step 6: Delete an edge
|
||||
println!("📍 Deleting edge 2 → 3...");
|
||||
let final_cut = mincut.delete_edge(2, 3)?;
|
||||
println!("Final minimum cut value: {}", final_cut);
|
||||
println!("→ The graph is now a chain: 1-2, 3-4, 1-3\n");
|
||||
|
||||
println!("✅ Success! You've computed your first dynamic minimum cut.");
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Running the Example
|
||||
|
||||
```bash
|
||||
cargo run --example my_first_mincut
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
|
||||
```
|
||||
🔷 Finding Minimum Cut in a Triangle
|
||||
|
||||
Minimum cut value: 2.0
|
||||
→ We need to remove 2 edge(s) to disconnect the graph
|
||||
|
||||
Partition:
|
||||
Side S (red): [1]
|
||||
Side T (blue): [2, 3]
|
||||
→ These two groups are separated by the cut
|
||||
|
||||
Edges in the minimum cut:
|
||||
1 ←→ 2 (weight: 1.0)
|
||||
1 ←→ 3 (weight: 1.0)
|
||||
→ These edges must be removed to separate the graph
|
||||
|
||||
📍 Adding edge 3 → 4 (weight 2.0)...
|
||||
New minimum cut value: 2.0
|
||||
→ Adding a leaf node increased connectivity
|
||||
|
||||
📍 Deleting edge 2 → 3...
|
||||
Final minimum cut value: 1.0
|
||||
→ The graph is now a chain: 1-2, 3-4, 1-3
|
||||
|
||||
✅ Success! You've computed your first dynamic minimum cut.
|
||||
```
|
||||
|
||||
### Breaking Down the Code
|
||||
|
||||
Let's understand each part:
|
||||
|
||||
#### 1. Building the Graph
|
||||
|
||||
```rust
|
||||
let mut mincut = MinCutBuilder::new()
|
||||
.exact()
|
||||
.with_edges(vec![
|
||||
(1, 2, 1.0),
|
||||
(2, 3, 1.0),
|
||||
(3, 1, 1.0),
|
||||
])
|
||||
.build()?;
|
||||
```
|
||||
|
||||
- **`MinCutBuilder::new()`**: Creates a new builder
|
||||
- **`.exact()`**: Use exact algorithm (guaranteed correct)
|
||||
- **`.with_edges(vec![...])`**: Add edges as `(source, target, weight)` tuples
|
||||
- **`.build()?`**: Construct the data structure
|
||||
|
||||
#### 2. Querying the Cut
|
||||
|
||||
```rust
|
||||
let cut_value = mincut.min_cut_value();
|
||||
```
|
||||
|
||||
This is **O(1)** — instant! The value is already computed.
|
||||
|
||||
#### 3. Getting the Partition
|
||||
|
||||
```rust
|
||||
let (side_s, side_t) = mincut.partition();
|
||||
```
|
||||
|
||||
Returns two vectors of vertex IDs showing which vertices are on each side of the cut.
|
||||
|
||||
#### 4. Dynamic Updates
|
||||
|
||||
```rust
|
||||
mincut.insert_edge(3, 4, 2.0)?; // Add edge
|
||||
mincut.delete_edge(2, 3)?; // Remove edge
|
||||
```
|
||||
|
||||
These operations update the minimum cut in **O(n^{o(1)})** amortized time — much faster than recomputing from scratch!
|
||||
|
||||
---
|
||||
|
||||
## 4. Understanding the Output
|
||||
|
||||
### What Do the Numbers Mean?
|
||||
|
||||
#### Minimum Cut Value
|
||||
|
||||
```rust
|
||||
let cut_value = mincut.min_cut_value(); // Example: 2.0
|
||||
```
|
||||
|
||||
**Interpretation:**
|
||||
- This is the **sum of weights** of edges you need to remove
|
||||
- For unweighted graphs (all edges weight 1.0), it's the **count of edges**
|
||||
- **Lower values** = weaker connectivity, easier to disconnect
|
||||
- **Higher values** = stronger connectivity, harder to disconnect
|
||||
|
||||
#### Partition
|
||||
|
||||
```rust
|
||||
let (side_s, side_t) = mincut.partition();
|
||||
// Example: ([1], [2, 3])
|
||||
```
|
||||
|
||||
**Interpretation:**
|
||||
- `side_s`: Vertex IDs on one side of the cut (arbitrarily chosen)
|
||||
- `side_t`: Vertex IDs on the other side
|
||||
- All edges connecting S to T are in the minimum cut
|
||||
- Vertices within S or T remain connected
|
||||
|
||||
#### Cut Edges
|
||||
|
||||
```rust
|
||||
let cut_edges = mincut.cut_edges();
|
||||
// Example: [(1, 2, 1.0), (1, 3, 1.0)]
|
||||
```
|
||||
|
||||
**Interpretation:**
|
||||
- These are the **specific edges** that form the minimum cut
|
||||
- Format: `(source_vertex, target_vertex, weight)`
|
||||
- Removing these edges disconnects the graph
|
||||
- The sum of weights equals the cut value
|
||||
|
||||
### Exact vs Approximate Results
|
||||
|
||||
```rust
|
||||
let result = mincut.min_cut();
|
||||
|
||||
if result.is_exact {
|
||||
println!("Guaranteed minimum: {}", result.value);
|
||||
} else {
|
||||
println!("Approximate: {} (±{}%)",
|
||||
result.value,
|
||||
(result.approximation_ratio - 1.0) * 100.0
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### Exact Mode
|
||||
- **`is_exact = true`**
|
||||
- Guaranteed to find the true minimum cut
|
||||
- Slower for very large graphs
|
||||
- Use when correctness is critical
|
||||
|
||||
#### Approximate Mode
|
||||
- **`is_exact = false`**
|
||||
- Returns a cut within `(1+ε)` of the minimum
|
||||
- Much faster for large graphs
|
||||
- Use when speed matters more than perfect accuracy
|
||||
|
||||
**Example:** With `ε = 0.1`:
|
||||
- If true minimum = 10, approximate returns between 10 and 11
|
||||
- Approximation ratio = 1.1 (10% tolerance)
|
||||
|
||||
### Performance Characteristics
|
||||
|
||||
```rust
|
||||
// Query: O(1) - instant!
|
||||
let value = mincut.min_cut_value();
|
||||
|
||||
// Insert edge: O(n^{o(1)}) - subpolynomial!
|
||||
mincut.insert_edge(u, v, weight)?;
|
||||
|
||||
// Delete edge: O(n^{o(1)}) - subpolynomial!
|
||||
mincut.delete_edge(u, v)?;
|
||||
```
|
||||
|
||||
**What is O(n^{o(1)})?**
|
||||
- Slower than O(1) but faster than O(n), O(log n), etc.
|
||||
- Example: O(n^{0.01}) or O(n^{1/log log n})
|
||||
- Much better than traditional O(m·n) algorithms
|
||||
- Enables real-time updates even for large graphs
|
||||
|
||||
---
|
||||
|
||||
## 5. Choosing Between Exact and Approximate
|
||||
|
||||
Use this flowchart to decide which mode to use:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start{What's your<br/>graph size?} --> Small{Less than<br/>10,000 nodes?}
|
||||
|
||||
Small -->|Yes| UseExact[Use EXACT mode]
|
||||
Small -->|No| Large{More than<br/>1 million nodes?}
|
||||
|
||||
Large -->|Yes| UseApprox[Use APPROXIMATE mode]
|
||||
Large -->|No| CheckAccuracy{Need guaranteed<br/>correctness?}
|
||||
|
||||
CheckAccuracy -->|Yes| UseExact2[Use EXACT mode]
|
||||
CheckAccuracy -->|No| CheckSpeed{Speed is<br/>critical?}
|
||||
|
||||
CheckSpeed -->|Yes| UseApprox2[Use APPROXIMATE mode]
|
||||
CheckSpeed -->|No| UseExact3[Use EXACT mode<br/>as default]
|
||||
|
||||
UseExact --> ExactCode["mincut = MinCutBuilder::new()
|
||||
.exact()
|
||||
.build()?"]
|
||||
|
||||
UseExact2 --> ExactCode
|
||||
UseExact3 --> ExactCode
|
||||
|
||||
UseApprox --> ApproxCode["mincut = MinCutBuilder::new()
|
||||
.approximate(0.1)
|
||||
.build()?"]
|
||||
|
||||
UseApprox2 --> ApproxCode
|
||||
|
||||
style Start fill:#e1f5ff
|
||||
style UseExact fill:#c8e6c9
|
||||
style UseExact2 fill:#c8e6c9
|
||||
style UseExact3 fill:#c8e6c9
|
||||
style UseApprox fill:#fff9c4
|
||||
style UseApprox2 fill:#fff9c4
|
||||
style ExactCode fill:#f0f0f0
|
||||
style ApproxCode fill:#f0f0f0
|
||||
```
|
||||
|
||||
### Quick Comparison
|
||||
|
||||
| Aspect | Exact Mode | Approximate Mode |
|
||||
|--------|-----------|------------------|
|
||||
| **Accuracy** | 100% correct | (1+ε) of optimal |
|
||||
| **Speed** | Moderate | Very fast |
|
||||
| **Memory** | O(n log n + m) | O(n log n / ε²) |
|
||||
| **Best For** | Small-medium graphs | Large graphs |
|
||||
| **Update Time** | O(n^{o(1)}) | O(n^{o(1)}) |
|
||||
|
||||
### Code Examples
|
||||
|
||||
**Exact Mode** (guaranteed correct):
|
||||
```rust
|
||||
let mut mincut = MinCutBuilder::new()
|
||||
.exact()
|
||||
.with_edges(edges)
|
||||
.build()?;
|
||||
|
||||
assert!(mincut.min_cut().is_exact);
|
||||
```
|
||||
|
||||
**Approximate Mode** (10% tolerance):
|
||||
```rust
|
||||
let mut mincut = MinCutBuilder::new()
|
||||
.approximate(0.1) // ε = 0.1
|
||||
.with_edges(edges)
|
||||
.build()?;
|
||||
|
||||
let result = mincut.min_cut();
|
||||
assert!(!result.is_exact);
|
||||
assert_eq!(result.approximation_ratio, 1.1);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Next Steps
|
||||
|
||||
Congratulations! You now understand the basics of minimum cuts and how to use RuVector MinCut. Here's where to go next:
|
||||
|
||||
### Learn More
|
||||
|
||||
| Topic | Link | What You'll Learn |
|
||||
|-------|------|------------------|
|
||||
| **Advanced API** | [02-advanced-api.md](02-advanced-api.md) | Batch operations, custom graphs, thread safety |
|
||||
| **Real-Time Monitoring** | [03-monitoring.md](03-monitoring.md) | Event notifications, thresholds, callbacks |
|
||||
| **Performance Tuning** | [04-performance.md](04-performance.md) | Benchmarking, optimization, scaling |
|
||||
| **Use Cases** | [05-use-cases.md](05-use-cases.md) | Network analysis, community detection, partitioning |
|
||||
| **Algorithm Details** | [../ALGORITHMS.md](../ALGORITHMS.md) | Mathematical foundations, proofs, complexity |
|
||||
| **Architecture** | [../ARCHITECTURE.md](../ARCHITECTURE.md) | Internal design, data structures, implementation |
|
||||
|
||||
### Try These Examples
|
||||
|
||||
RuVector MinCut comes with several examples you can run:
|
||||
|
||||
```bash
|
||||
# Basic minimum cut operations
|
||||
cargo run --example basic
|
||||
|
||||
# Graph sparsification
|
||||
cargo run --example sparsify_demo
|
||||
|
||||
# Local k-cut algorithm
|
||||
cargo run --example localkcut_demo
|
||||
|
||||
# Real-time monitoring (requires 'monitoring' feature)
|
||||
cargo run --example monitoring --features monitoring
|
||||
|
||||
# Performance benchmarking
|
||||
cargo run --example benchmark --release
|
||||
```
|
||||
|
||||
### Common Tasks
|
||||
|
||||
#### Task 1: Analyze Your Own Graph
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::{MinCutBuilder, DynamicMinCut};
|
||||
|
||||
fn analyze_network(edges: Vec<(u32, u32, f64)>) -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut mincut = MinCutBuilder::new()
|
||||
.exact()
|
||||
.with_edges(edges)
|
||||
.build()?;
|
||||
|
||||
println!("Network vulnerability: {}", mincut.min_cut_value());
|
||||
println!("Critical edges: {:?}", mincut.cut_edges());
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
#### Task 2: Monitor Real-Time Changes
|
||||
|
||||
```rust
|
||||
#[cfg(feature = "monitoring")]
|
||||
use ruvector_mincut::{MonitorBuilder, EventType};
|
||||
|
||||
fn setup_monitoring() {
|
||||
let monitor = MonitorBuilder::new()
|
||||
.threshold_below(5.0, "critical")
|
||||
.on_event_type(EventType::CutDecreased, "alert", |event| {
|
||||
eprintln!("⚠️ WARNING: Cut decreased to {}", event.new_value);
|
||||
})
|
||||
.build();
|
||||
|
||||
// Attach to your mincut structure...
|
||||
}
|
||||
```
|
||||
|
||||
#### Task 3: Batch Process Updates
|
||||
|
||||
```rust
|
||||
fn batch_updates(mincut: &mut impl DynamicMinCut,
|
||||
new_edges: &[(u32, u32, f64)]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
// Insert many edges at once
|
||||
for (u, v, w) in new_edges {
|
||||
mincut.insert_edge(*u, *v, *w)?;
|
||||
}
|
||||
|
||||
// Query triggers lazy evaluation
|
||||
let current_cut = mincut.min_cut_value();
|
||||
println!("Updated minimum cut: {}", current_cut);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Get Help
|
||||
|
||||
- **📖 Documentation**: [docs.rs/ruvector-mincut](https://docs.rs/ruvector-mincut)
|
||||
- **🐙 GitHub Issues**: [Report bugs or ask questions](https://github.com/ruvnet/ruvector/issues)
|
||||
- **💬 Discussions**: [Community forum](https://github.com/ruvnet/ruvector/discussions)
|
||||
- **🌐 Website**: [ruv.io](https://ruv.io)
|
||||
|
||||
### Keep Learning
|
||||
|
||||
The minimum cut problem connects to many fascinating areas of computer science:
|
||||
|
||||
- **Network Flow**: Max-flow/min-cut theorem
|
||||
- **Graph Theory**: Connectivity, separators, spanning trees
|
||||
- **Optimization**: Linear programming, approximation algorithms
|
||||
- **Distributed Systems**: Partition tolerance, consensus
|
||||
- **Machine Learning**: Graph neural networks, clustering
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Builder Pattern
|
||||
|
||||
```rust
|
||||
MinCutBuilder::new()
|
||||
.exact() // or .approximate(0.1)
|
||||
.with_edges(edges) // Initial edges
|
||||
.with_capacity(10000) // Preallocate capacity
|
||||
.build()? // Construct
|
||||
```
|
||||
|
||||
### Core Operations
|
||||
|
||||
```rust
|
||||
mincut.min_cut_value() // Get cut value (O(1))
|
||||
mincut.partition() // Get partition (O(n))
|
||||
mincut.cut_edges() // Get cut edges (O(m))
|
||||
mincut.insert_edge(u, v, w)? // Add edge (O(n^{o(1)}))
|
||||
mincut.delete_edge(u, v)? // Remove edge (O(n^{o(1)}))
|
||||
```
|
||||
|
||||
### Result Inspection
|
||||
|
||||
```rust
|
||||
let result = mincut.min_cut();
|
||||
result.value // Cut value
|
||||
result.is_exact // true if exact mode
|
||||
result.approximation_ratio // 1.0 if exact, >1.0 if approximate
|
||||
result.edges // Edges in the cut
|
||||
result.partition // (S, T) vertex sets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Happy computing! 🚀**
|
||||
|
||||
> **Pro Tip**: Start simple with exact mode on small graphs, then switch to approximate mode as your graphs grow. The API is identical!
|
||||
655
vendor/ruvector/crates/ruvector-mincut/docs/guide/02-core-concepts.md
vendored
Normal file
655
vendor/ruvector/crates/ruvector-mincut/docs/guide/02-core-concepts.md
vendored
Normal file
@@ -0,0 +1,655 @@
|
||||
# Core Concepts
|
||||
|
||||
This guide explains the fundamental concepts behind minimum cut algorithms in accessible language. Whether you're new to graph theory or experienced with algorithms, this guide will help you understand what makes RuVector's minimum cut implementation special.
|
||||
|
||||
---
|
||||
|
||||
## 1. Graph Basics
|
||||
|
||||
### What is a Graph?
|
||||
|
||||
Think of a graph like a social network or a map:
|
||||
|
||||
- **Vertices (Nodes)**: These are the "things" in your system
|
||||
- Cities on a map
|
||||
- People in a social network
|
||||
- Computers in a network
|
||||
- Pixels in an image
|
||||
|
||||
- **Edges (Links)**: These are the connections between things
|
||||
- Roads between cities
|
||||
- Friendships between people
|
||||
- Network cables between computers
|
||||
- Similarity between adjacent pixels
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Alice] ---|Friend| B[Bob]
|
||||
B ---|Friend| C[Carol]
|
||||
A ---|Friend| C
|
||||
C ---|Friend| D[Dave]
|
||||
B ---|Friend| D
|
||||
|
||||
style A fill:#e1f5ff
|
||||
style B fill:#e1f5ff
|
||||
style C fill:#e1f5ff
|
||||
style D fill:#e1f5ff
|
||||
```
|
||||
|
||||
### Weighted vs Unweighted Graphs
|
||||
|
||||
**Unweighted Graph**: All connections are equal
|
||||
- Example: "Is there a friendship?" (yes/no)
|
||||
|
||||
**Weighted Graph**: Connections have different strengths or capacities
|
||||
- Example: "How strong is the friendship?" (1-10 scale)
|
||||
- Example: "What's the bandwidth of this network cable?" (100 Mbps, 1 Gbps, etc.)
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Unweighted Graph"
|
||||
A1[City A] --- B1[City B]
|
||||
B1 --- C1[City C]
|
||||
A1 --- C1
|
||||
end
|
||||
|
||||
subgraph "Weighted Graph"
|
||||
A2[City A] ---|50 km| B2[City B]
|
||||
B2 ---|30 km| C2[City C]
|
||||
A2 ---|80 km| C2
|
||||
end
|
||||
|
||||
style A1 fill:#ffe1e1
|
||||
style B1 fill:#ffe1e1
|
||||
style C1 fill:#ffe1e1
|
||||
style A2 fill:#e1ffe1
|
||||
style B2 fill:#e1ffe1
|
||||
style C2 fill:#e1ffe1
|
||||
```
|
||||
|
||||
### Directed vs Undirected Graphs
|
||||
|
||||
**Undirected**: Connections work both ways
|
||||
- Example: Roads (usually bidirectional)
|
||||
- Example: Mutual friendships
|
||||
|
||||
**Undirected**: Connections have a direction
|
||||
- Example: One-way streets
|
||||
- Example: Twitter follows (Alice follows Bob doesn't mean Bob follows Alice)
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Undirected (Bidirectional)"
|
||||
A1[A] --- B1[B]
|
||||
B1 --- C1[C]
|
||||
end
|
||||
|
||||
subgraph "Directed (One-way)"
|
||||
A2[A] --> B2[B]
|
||||
B2 --> C2[C]
|
||||
C2 --> A2
|
||||
end
|
||||
```
|
||||
|
||||
**RuVector focuses on undirected, weighted graphs** for minimum cut problems.
|
||||
|
||||
---
|
||||
|
||||
## 2. What is Minimum Cut?
|
||||
|
||||
### Definition
|
||||
|
||||
A **cut** in a graph divides vertices into two groups. The **minimum cut** is the division that requires removing the fewest (or lowest-weight) edges.
|
||||
|
||||
Think of it like this:
|
||||
- Imagine a network of pipes carrying water
|
||||
- A cut is choosing which pipes to block to split the network in two
|
||||
- The minimum cut finds the weakest point - the smallest set of pipes that, if blocked, would separate the network
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Original Graph"
|
||||
A[A] ---|2| B[B]
|
||||
A ---|3| C[C]
|
||||
B ---|1| D[D]
|
||||
C ---|1| D
|
||||
B ---|4| C
|
||||
end
|
||||
|
||||
subgraph "Minimum Cut (weight = 2)"
|
||||
A1[A] ---|2| B1[B]
|
||||
A1 ---|3| C1[C]
|
||||
B1 -.X.-|1| D1[D]
|
||||
C1 -.X.-|1| D1
|
||||
B1 ---|4| C1
|
||||
|
||||
style A1 fill:#ffcccc
|
||||
style B1 fill:#ffcccc
|
||||
style C1 fill:#ffcccc
|
||||
style D1 fill:#ccffcc
|
||||
end
|
||||
```
|
||||
|
||||
In the example above:
|
||||
- Cutting edges B-D and C-D (total weight = 1 + 1 = 2) separates the graph
|
||||
- This is the minimum cut because no smaller cut exists
|
||||
- The red group {A, B, C} is separated from the green group {D}
|
||||
|
||||
### Why Minimum Cut Matters
|
||||
|
||||
Minimum cut algorithms solve real-world problems:
|
||||
|
||||
#### 1. **Network Reliability**
|
||||
Find the weakest point in your infrastructure:
|
||||
- Which network links, if they fail, would split your system?
|
||||
- What's the minimum bandwidth bottleneck?
|
||||
- Where should you add redundancy?
|
||||
|
||||
#### 2. **Image Segmentation**
|
||||
Separate objects from backgrounds:
|
||||
- Each pixel is a vertex
|
||||
- Similar adjacent pixels have high-weight edges
|
||||
- Minimum cut finds natural object boundaries
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Image Pixels"
|
||||
P1[Sky] ---|9| P2[Sky]
|
||||
P2 ---|9| P3[Sky]
|
||||
P3 ---|2| P4[Tree]
|
||||
P4 ---|8| P5[Tree]
|
||||
P5 ---|8| P6[Tree]
|
||||
end
|
||||
|
||||
style P1 fill:#87ceeb
|
||||
style P2 fill:#87ceeb
|
||||
style P3 fill:#87ceeb
|
||||
style P4 fill:#228b22
|
||||
style P5 fill:#228b22
|
||||
style P6 fill:#228b22
|
||||
```
|
||||
|
||||
#### 3. **Community Detection**
|
||||
Find natural groupings in social networks:
|
||||
- Strong connections within communities
|
||||
- Weak connections between communities
|
||||
- Minimum cut reveals community boundaries
|
||||
|
||||
#### 4. **VLSI Design**
|
||||
Partition circuits to minimize connections between chips:
|
||||
- Reduces manufacturing complexity
|
||||
- Minimizes communication overhead
|
||||
- Optimizes physical layout
|
||||
|
||||
### Global Minimum Cut vs S-T Minimum Cut
|
||||
|
||||
There are two types of minimum cut problems:
|
||||
|
||||
#### **S-T Minimum Cut (Terminal Cut)**
|
||||
- You specify two vertices: source (s) and sink (t)
|
||||
- Find the minimum cut that separates s from t
|
||||
- Common in flow networks and image segmentation
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
S[Source S] ---|5| A[A]
|
||||
S ---|3| B[B]
|
||||
A ---|2| T[Sink T]
|
||||
B ---|4| T
|
||||
A ---|1| B
|
||||
|
||||
style S fill:#ffcccc
|
||||
style A fill:#ffcccc
|
||||
style B fill:#ccffcc
|
||||
style T fill:#ccffcc
|
||||
```
|
||||
|
||||
#### **Global Minimum Cut (All-Pairs)**
|
||||
- No specific source/sink specified
|
||||
- Find the absolute minimum cut across the entire graph
|
||||
- Harder problem, but more general
|
||||
|
||||
**RuVector implements global minimum cut algorithms** - the most general and challenging variant.
|
||||
|
||||
---
|
||||
|
||||
## 3. Dynamic vs Static Algorithms
|
||||
|
||||
### The Static Approach
|
||||
|
||||
Traditional algorithms start from scratch every time:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Algorithm
|
||||
participant Graph
|
||||
|
||||
User->>Graph: Initial graph with 1000 edges
|
||||
User->>Algorithm: Compute minimum cut
|
||||
Algorithm->>Algorithm: Process all 1000 edges
|
||||
Algorithm->>User: Result (takes 10 seconds)
|
||||
|
||||
User->>Graph: Add 1 edge
|
||||
User->>Algorithm: Compute minimum cut again
|
||||
Algorithm->>Algorithm: Reprocess all 1001 edges from scratch
|
||||
Algorithm->>User: Result (takes 10 seconds again!)
|
||||
|
||||
Note over User,Algorithm: Inefficient: Full recomputation every time
|
||||
```
|
||||
|
||||
**Problem**: If you add/remove just one edge, static algorithms recompute everything!
|
||||
|
||||
### The Dynamic Approach (Revolutionary!)
|
||||
|
||||
Dynamic algorithms maintain the solution incrementally:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant DynAlg as Dynamic Algorithm
|
||||
participant Graph
|
||||
|
||||
User->>Graph: Initial graph with 1000 edges
|
||||
User->>DynAlg: Compute minimum cut
|
||||
DynAlg->>DynAlg: Process all 1000 edges, build data structures
|
||||
DynAlg->>User: Result (takes 10 seconds)
|
||||
|
||||
User->>Graph: Add 1 edge
|
||||
User->>DynAlg: Update minimum cut
|
||||
DynAlg->>DynAlg: Update only affected parts
|
||||
DynAlg->>User: Result (takes 0.1 seconds!)
|
||||
|
||||
Note over User,DynAlg: Efficient: Incremental updates only
|
||||
```
|
||||
|
||||
**Advantage**: Updates are typically much faster than full recomputation!
|
||||
|
||||
### Why Dynamic is Revolutionary
|
||||
|
||||
Consider a practical scenario:
|
||||
|
||||
| Operation | Static Algorithm | Dynamic Algorithm |
|
||||
|-----------|------------------|-------------------|
|
||||
| Initial computation (10,000 edges) | 100 seconds | 100 seconds |
|
||||
| Add 1 edge | 100 seconds | 0.5 seconds |
|
||||
| Add 100 edges (one at a time) | 10,000 seconds (2.7 hours!) | 50 seconds |
|
||||
| **Speed improvement** | — | **200× faster** |
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Change in Graph] --> B{Use Dynamic Algorithm?}
|
||||
B -->|Yes| C[Update incrementally]
|
||||
B -->|No| D[Recompute from scratch]
|
||||
C --> E[Fast Update 0.5s]
|
||||
D --> F[Slow Recompute 100s]
|
||||
|
||||
style C fill:#90EE90
|
||||
style D fill:#FFB6C6
|
||||
style E fill:#90EE90
|
||||
style F fill:#FFB6C6
|
||||
```
|
||||
|
||||
### Amortized vs Worst-Case Complexity
|
||||
|
||||
Dynamic algorithms have two complexity measures:
|
||||
|
||||
#### **Amortized Complexity**
|
||||
- Average time per operation over many operations
|
||||
- Usually much better than worst-case
|
||||
- Example: O(log² n) per edge insertion
|
||||
|
||||
#### **Worst-Case Complexity**
|
||||
- Maximum time for a single operation
|
||||
- Guarantees for real-time systems
|
||||
- Example: O(log⁴ n) per edge insertion
|
||||
|
||||
**RuVector provides both**:
|
||||
- **Standard algorithm**: Best amortized complexity O(n^{o(1)})
|
||||
- **PolylogConnectivity**: Deterministic worst-case O(log⁴ n)
|
||||
|
||||
---
|
||||
|
||||
## 4. Algorithm Choices
|
||||
|
||||
RuVector provides three cutting-edge algorithms from recent research papers (2024-2025). Here's when to use each:
|
||||
|
||||
### 4.1 Exact Algorithm (Default)
|
||||
|
||||
**Based on**: "A Õ(n^{o(1)})-Approximation Algorithm for Minimum Cut" (Chen et al., 2024)
|
||||
|
||||
**Complexity**: O(n^{o(1)}) amortized per operation
|
||||
|
||||
**When to use**:
|
||||
- ✅ You need the exact minimum cut value
|
||||
- ✅ Your graph changes frequently (dynamic updates)
|
||||
- ✅ You want the best average-case performance
|
||||
- ✅ General-purpose applications
|
||||
|
||||
**Trade-offs**:
|
||||
- Slower worst-case than approximate algorithm
|
||||
- Best for most applications
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::{MinCutWrapper, MinCutAlgorithm};
|
||||
|
||||
let mut wrapper = MinCutWrapper::new(
|
||||
num_vertices,
|
||||
MinCutAlgorithm::Exact
|
||||
);
|
||||
```
|
||||
|
||||
### 4.2 Approximate Algorithm ((1+ε)-approximation)
|
||||
|
||||
**Based on**: "Dynamic (1+ε)-Approximate Minimum Cut in Subpolynomial Time per Operation" (Cen et al., 2025)
|
||||
|
||||
**Complexity**: Õ(1/ε²) amortized per operation (subpolynomial in n!)
|
||||
|
||||
**When to use**:
|
||||
- ✅ You can tolerate small approximation error
|
||||
- ✅ You need extremely fast updates
|
||||
- ✅ Your graph is very large (millions of vertices)
|
||||
- ✅ You want cutting-edge performance
|
||||
|
||||
**Trade-offs**:
|
||||
- Result is within (1+ε) of optimal (e.g., ε=0.1 → 10% error bound)
|
||||
- **Fastest algorithm** for large graphs
|
||||
|
||||
```rust
|
||||
let mut wrapper = MinCutWrapper::new_approx(
|
||||
num_vertices,
|
||||
0.1 // ε = 10% approximation
|
||||
);
|
||||
```
|
||||
|
||||
**Example**: If true minimum cut is 100, approximate algorithm returns 100-110.
|
||||
|
||||
### 4.3 PolylogConnectivity (Deterministic Worst-Case)
|
||||
|
||||
**Based on**: "Incremental (1+ε)-Approximate Dynamic Connectivity with polylog Worst-Case Time per Update" (Cen et al., 2025)
|
||||
|
||||
**Complexity**: O(log⁴ n / ε²) worst-case per operation
|
||||
|
||||
**When to use**:
|
||||
- ✅ You need **guaranteed** worst-case performance
|
||||
- ✅ Real-time systems with strict latency requirements
|
||||
- ✅ Safety-critical applications
|
||||
- ✅ You need predictable performance (no spikes)
|
||||
|
||||
**Trade-offs**:
|
||||
- Slightly slower than amortized algorithms on average
|
||||
- Provides deterministic guarantees
|
||||
|
||||
```rust
|
||||
let mut wrapper = MinCutWrapper::new_polylog_connectivity(
|
||||
num_vertices,
|
||||
0.1 // ε = 10% approximation
|
||||
);
|
||||
```
|
||||
|
||||
### Performance Comparison
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Performance Characteristics"
|
||||
A[Exact Algorithm] --> A1["Amortized: O(n^o1)"]
|
||||
A --> A2[Exact results]
|
||||
A --> A3[Best general-purpose]
|
||||
|
||||
B[Approximate] --> B1["Amortized: Õ(1/ε²)"]
|
||||
B --> B2[±ε error]
|
||||
B --> B3[Fastest updates]
|
||||
|
||||
C[PolylogConnectivity] --> C1["Worst-case: O(log⁴ n / ε²)"]
|
||||
C --> C2[±ε error]
|
||||
C --> C3[Predictable latency]
|
||||
end
|
||||
|
||||
style A fill:#e1f5ff
|
||||
style B fill:#ffe1e1
|
||||
style C fill:#e1ffe1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Data Structures
|
||||
|
||||
Dynamic minimum cut algorithms rely on sophisticated data structures. You don't need to understand these deeply to use RuVector, but knowing they exist helps appreciate the complexity.
|
||||
|
||||
### 5.1 Link-Cut Trees
|
||||
|
||||
**Purpose**: Maintain connectivity in forests with dynamic edge insertions/deletions
|
||||
|
||||
**Operations**:
|
||||
- `link(u, v)`: Connect two trees
|
||||
- `cut(u, v)`: Disconnect an edge
|
||||
- `find_root(v)`: Find root of v's tree
|
||||
- `path_aggregate(u, v)`: Aggregate values on path from u to v
|
||||
|
||||
**Time Complexity**: O(log n) per operation (amortized)
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Link-Cut Tree Structure"
|
||||
R1[Root] --> C1[Child 1]
|
||||
R1 --> C2[Child 2]
|
||||
C1 --> G1[Grandchild 1]
|
||||
C1 --> G2[Grandchild 2]
|
||||
C2 --> G3[Grandchild 3]
|
||||
end
|
||||
|
||||
subgraph "Operations"
|
||||
O1[link: Add edge]
|
||||
O2[cut: Remove edge]
|
||||
O3[find_root: Query root]
|
||||
O4[path_aggregate: Sum on path]
|
||||
end
|
||||
|
||||
style R1 fill:#ffcccc
|
||||
style C1 fill:#ccffcc
|
||||
style C2 fill:#ccffcc
|
||||
style G1 fill:#ccccff
|
||||
style G2 fill:#ccccff
|
||||
style G3 fill:#ccccff
|
||||
```
|
||||
|
||||
**Used in**: All three algorithms for maintaining spanning forests
|
||||
|
||||
### 5.2 Euler Tour Trees
|
||||
|
||||
**Purpose**: Alternative dynamic connectivity structure with different trade-offs
|
||||
|
||||
**Key Idea**: Represent tree as a cyclic sequence (Euler tour)
|
||||
|
||||
**Advantages**:
|
||||
- Efficient subtree operations
|
||||
- Good for maintaining subtree properties
|
||||
- Deterministic performance
|
||||
|
||||
**Time Complexity**: O(log n) per operation
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[A] --> B[B]
|
||||
A --> C[C]
|
||||
B --> D[D]
|
||||
B --> E[E]
|
||||
|
||||
subgraph "Euler Tour Sequence"
|
||||
direction LR
|
||||
ET[A → B → D → B → E → B → A → C → A]
|
||||
end
|
||||
|
||||
style A fill:#ffcccc
|
||||
style B fill:#ccffcc
|
||||
style C fill:#ccccff
|
||||
style D fill:#ffffcc
|
||||
style E fill:#ffccff
|
||||
```
|
||||
|
||||
**Used in**: PolylogConnectivity algorithm for deterministic guarantees
|
||||
|
||||
### 5.3 Hierarchical Decomposition
|
||||
|
||||
**Purpose**: Partition graph into levels with decreasing density
|
||||
|
||||
**Key Idea**:
|
||||
- Level 0: Original graph
|
||||
- Level i: Graph with edges of weight ≥ 2^i
|
||||
- Higher levels are sparser
|
||||
|
||||
**Advantages**:
|
||||
- Focus computation on relevant parts
|
||||
- Skip unnecessary levels
|
||||
- Efficient updates
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Level 0 (All edges)"
|
||||
L0A[A] ---|1| L0B[B]
|
||||
L0A ---|2| L0C[C]
|
||||
L0A ---|4| L0D[D]
|
||||
L0B ---|8| L0C
|
||||
end
|
||||
|
||||
subgraph "Level 1 (Weight ≥ 2)"
|
||||
L1A[A] ---|2| L1C[C]
|
||||
L1A ---|4| L1D[D]
|
||||
L1B[B] ---|8| L1C
|
||||
end
|
||||
|
||||
subgraph "Level 2 (Weight ≥ 4)"
|
||||
L2A[A] ---|4| L2D[D]
|
||||
L2B[B] ---|8| L2C[C]
|
||||
end
|
||||
|
||||
subgraph "Level 3 (Weight ≥ 8)"
|
||||
L3B[B] ---|8| L3C[C]
|
||||
end
|
||||
|
||||
style L0A fill:#ffcccc
|
||||
style L1A fill:#ccffcc
|
||||
style L2A fill:#ccccff
|
||||
style L3B fill:#ffffcc
|
||||
```
|
||||
|
||||
**Used in**: Approximate and PolylogConnectivity algorithms for hierarchical graph processing
|
||||
|
||||
### 5.4 Local k-Cut Hierarchy
|
||||
|
||||
**Purpose**: Maintain minimum cuts of varying connectivity
|
||||
|
||||
**Key Idea**:
|
||||
- Store cuts of different sizes (1-cut, 2-cut, ..., k-cut)
|
||||
- Update only affected levels
|
||||
- Query appropriate level for minimum cut
|
||||
|
||||
**Advantages**:
|
||||
- Efficient querying of different cut sizes
|
||||
- Incremental updates
|
||||
- Supports connectivity curve analysis
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
H1[1-Cut: λ=2] --> H2[2-Cut: λ=5]
|
||||
H2 --> H3[3-Cut: λ=7]
|
||||
H3 --> H4[4-Cut: λ=9]
|
||||
|
||||
style H1 fill:#ffcccc
|
||||
style H2 fill:#ccffcc
|
||||
style H3 fill:#ccccff
|
||||
style H4 fill:#ffffcc
|
||||
```
|
||||
|
||||
**Used in**: All algorithms for maintaining cut hierarchies
|
||||
|
||||
---
|
||||
|
||||
## 6. Which Algorithm Should I Use?
|
||||
|
||||
Use this decision flowchart to choose the right algorithm:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start[Which algorithm?] --> Q1{Need exact result?}
|
||||
|
||||
Q1 -->|Yes| Exact[Use Exact Algorithm]
|
||||
Q1 -->|No, approximation OK| Q2{Need worst-case guarantees?}
|
||||
|
||||
Q2 -->|Yes, real-time/safety-critical| Polylog[Use PolylogConnectivity]
|
||||
Q2 -->|No, average case is fine| Q3{Graph size?}
|
||||
|
||||
Q3 -->|Small < 10K vertices| Exact2[Use Exact Algorithm]
|
||||
Q3 -->|Large > 10K vertices| Approx[Use Approximate Algorithm]
|
||||
|
||||
Exact --> E1["MinCutAlgorithm::Exact<br/>Best general-purpose"]
|
||||
Exact2 --> E1
|
||||
Approx --> A1["new_approx(n, 0.1)<br/>10% error, fastest"]
|
||||
Polylog --> P1["new_polylog_connectivity(n, 0.1)<br/>Predictable latency"]
|
||||
|
||||
style Exact fill:#90EE90
|
||||
style Exact2 fill:#90EE90
|
||||
style Approx fill:#FFD700
|
||||
style Polylog fill:#87CEEB
|
||||
style E1 fill:#90EE90
|
||||
style A1 fill:#FFD700
|
||||
style P1 fill:#87CEEB
|
||||
```
|
||||
|
||||
### Quick Reference Table
|
||||
|
||||
| Your Needs | Recommended Algorithm | Configuration |
|
||||
|------------|----------------------|---------------|
|
||||
| General-purpose, need exact results | **Exact** | `MinCutAlgorithm::Exact` |
|
||||
| Large graph (>10K vertices), can tolerate 5-10% error | **Approximate** | `new_approx(n, 0.1)` |
|
||||
| Real-time system, need guaranteed latency | **PolylogConnectivity** | `new_polylog_connectivity(n, 0.1)` |
|
||||
| Interactive application with frequent updates | **Approximate** | `new_approx(n, 0.05)` |
|
||||
| Scientific computing, need precision | **Exact** | `MinCutAlgorithm::Exact` |
|
||||
| Image segmentation (can accept small errors) | **Approximate** | `new_approx(n, 0.1)` |
|
||||
| Network monitoring (need alerts) | **PolylogConnectivity** | `new_polylog_connectivity(n, 0.05)` |
|
||||
|
||||
### Performance Guidelines
|
||||
|
||||
**Exact Algorithm**:
|
||||
```rust
|
||||
// Best for: Most applications
|
||||
let mut mincut = MinCutWrapper::new(1000, MinCutAlgorithm::Exact);
|
||||
```
|
||||
|
||||
**Approximate Algorithm**:
|
||||
```rust
|
||||
// Best for: Large graphs, speed-critical
|
||||
let mut mincut = MinCutWrapper::new_approx(
|
||||
100_000, // Large graph
|
||||
0.1 // 10% approximation is usually fine
|
||||
);
|
||||
```
|
||||
|
||||
**PolylogConnectivity**:
|
||||
```rust
|
||||
// Best for: Real-time systems
|
||||
let mut mincut = MinCutWrapper::new_polylog_connectivity(
|
||||
50_000, // Medium-large graph
|
||||
0.05 // Tight approximation for accuracy
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
You now understand:
|
||||
|
||||
1. **Graph fundamentals**: Vertices, edges, weights, and directions
|
||||
2. **Minimum cut**: Finding the weakest separation in a graph
|
||||
3. **Dynamic algorithms**: Why incremental updates are revolutionary (200× faster!)
|
||||
4. **Algorithm choices**: Exact, approximate, and worst-case deterministic options
|
||||
5. **Data structures**: The sophisticated machinery powering fast dynamic updates
|
||||
6. **Decision making**: How to choose the right algorithm for your application
|
||||
|
||||
**Next Steps**:
|
||||
- Read [API Reference](./03-api-reference.md) for detailed function documentation
|
||||
- Explore [Examples](./04-examples.md) for practical use cases
|
||||
- Check out [Performance Guide](./05-performance.md) for optimization tips
|
||||
|
||||
**Key Takeaway**: RuVector gives you state-of-the-art dynamic minimum cut algorithms that are 100-200× faster than static approaches for graphs that change over time. Choose your algorithm based on whether you need exact results, maximum speed, or worst-case guarantees.
|
||||
1605
vendor/ruvector/crates/ruvector-mincut/docs/guide/03-practical-applications.md
vendored
Normal file
1605
vendor/ruvector/crates/ruvector-mincut/docs/guide/03-practical-applications.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
2116
vendor/ruvector/crates/ruvector-mincut/docs/guide/04-integration-guide.md
vendored
Normal file
2116
vendor/ruvector/crates/ruvector-mincut/docs/guide/04-integration-guide.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
1885
vendor/ruvector/crates/ruvector-mincut/docs/guide/05-advanced-examples.md
vendored
Normal file
1885
vendor/ruvector/crates/ruvector-mincut/docs/guide/05-advanced-examples.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
827
vendor/ruvector/crates/ruvector-mincut/docs/guide/06-ecosystem.md
vendored
Normal file
827
vendor/ruvector/crates/ruvector-mincut/docs/guide/06-ecosystem.md
vendored
Normal file
@@ -0,0 +1,827 @@
|
||||
# RuVector Ecosystem Guide
|
||||
|
||||
This guide provides an overview of the RuVector ecosystem, showing how `ruvector-mincut` integrates with other crates in the family and the broader ruv.io platform.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [RuVector Family](#ruvector-family)
|
||||
- [ruvector-mincut Bindings](#ruvector-mincut-bindings)
|
||||
- [Midstream Integration](#midstream-integration)
|
||||
- [Advanced Integrations](#advanced-integrations)
|
||||
- [ruv.io Platform](#ruvio-platform)
|
||||
- [Ecosystem Architecture](#ecosystem-architecture)
|
||||
- [Resources](#resources)
|
||||
|
||||
## RuVector Family
|
||||
|
||||
The RuVector family is a collection of high-performance Rust crates for vector operations, graph analytics, and machine learning, optimized for SIMD and modern hardware.
|
||||
|
||||
### Core Crates
|
||||
|
||||
#### ruvector-core
|
||||
**Foundation for all RuVector operations**
|
||||
|
||||
- **SIMD Primitives**: Hardware-accelerated vector operations
|
||||
- **Memory Management**: Efficient allocation and alignment
|
||||
- **Math Kernels**: Optimized dot products, distances, norms
|
||||
- **Platform Abstractions**: CPU feature detection, WASM support
|
||||
|
||||
```rust
|
||||
use ruvector_core::{SimdVector, Distance};
|
||||
|
||||
let vec1 = SimdVector::from_slice(&[1.0, 2.0, 3.0, 4.0]);
|
||||
let vec2 = SimdVector::from_slice(&[4.0, 3.0, 2.0, 1.0]);
|
||||
let distance = vec1.euclidean_distance(&vec2);
|
||||
```
|
||||
|
||||
**Use Cases**: Building custom vector operations, low-level optimization
|
||||
|
||||
---
|
||||
|
||||
#### ruvector-graph
|
||||
**Graph database with vector embeddings**
|
||||
|
||||
- **Property Graphs**: Nodes and edges with arbitrary properties
|
||||
- **Vector Embeddings**: Associate embeddings with graph elements
|
||||
- **Graph Queries**: Traversal, pattern matching, shortest paths
|
||||
- **Persistence**: Efficient storage and retrieval
|
||||
|
||||
```rust
|
||||
use ruvector_graph::{Graph, Node, Edge};
|
||||
|
||||
let mut graph = Graph::new();
|
||||
let node1 = graph.add_node_with_embedding(
|
||||
"user_123",
|
||||
&[0.1, 0.2, 0.3], // User embedding
|
||||
);
|
||||
```
|
||||
|
||||
**Use Cases**: Knowledge graphs, social networks, recommendation systems
|
||||
|
||||
---
|
||||
|
||||
#### ruvector-index
|
||||
**High-performance vector indexing**
|
||||
|
||||
- **Multiple Algorithms**: HNSW, IVF, Product Quantization
|
||||
- **Hybrid Search**: Combine vector similarity with filters
|
||||
- **Scalability**: Billions of vectors, sub-millisecond queries
|
||||
- **Incremental Updates**: Add/remove vectors dynamically
|
||||
|
||||
```rust
|
||||
use ruvector_index::{HnswIndex, IndexConfig};
|
||||
|
||||
let config = IndexConfig::default()
|
||||
.with_ef_construction(200)
|
||||
.with_m(16);
|
||||
let index = HnswIndex::new(config);
|
||||
```
|
||||
|
||||
**Use Cases**: Semantic search, image retrieval, deduplication
|
||||
|
||||
---
|
||||
|
||||
#### ruvector-mincut
|
||||
**Graph partitioning and min-cut algorithms (this crate)**
|
||||
|
||||
- **Min-Cut Algorithms**: Karger, Stoer-Wagner, Gomory-Hu
|
||||
- **Graph Partitioning**: Balanced cuts, hierarchical decomposition
|
||||
- **Connectivity Analysis**: Edge connectivity, cut enumeration
|
||||
- **WASM/Node Bindings**: Deploy anywhere
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::{Graph, karger_min_cut};
|
||||
|
||||
let graph = Graph::from_edges(&[(0, 1), (1, 2), (2, 0)]);
|
||||
let (cut_value, partition) = karger_min_cut(&graph, 1000);
|
||||
```
|
||||
|
||||
**Use Cases**: Network analysis, community detection, circuit design
|
||||
|
||||
---
|
||||
|
||||
#### ruvector-attention
|
||||
**Attention mechanisms for transformers**
|
||||
|
||||
- **Multi-Head Attention**: Self-attention, cross-attention
|
||||
- **Optimized Kernels**: Flash Attention, memory-efficient attention
|
||||
- **Position Encodings**: Rotary, ALiBi, learned embeddings
|
||||
- **Masking Support**: Causal, bidirectional, custom masks
|
||||
|
||||
```rust
|
||||
use ruvector_attention::{MultiHeadAttention, AttentionConfig};
|
||||
|
||||
let config = AttentionConfig::new(512, 8); // 512 dim, 8 heads
|
||||
let mha = MultiHeadAttention::new(config);
|
||||
let output = mha.forward(&query, &key, &value, mask);
|
||||
```
|
||||
|
||||
**Use Cases**: Transformers, language models, vision transformers
|
||||
|
||||
---
|
||||
|
||||
#### ruvector-gnn
|
||||
**Graph Neural Networks**
|
||||
|
||||
- **GNN Layers**: GCN, GAT, GraphSAGE, GIN
|
||||
- **Message Passing**: Efficient aggregation on large graphs
|
||||
- **Heterogeneous Graphs**: Multiple node/edge types
|
||||
- **Temporal Graphs**: Dynamic graph learning
|
||||
|
||||
```rust
|
||||
use ruvector_gnn::{GCNLayer, GraphConvolution};
|
||||
|
||||
let gcn = GCNLayer::new(128, 64); // 128 -> 64 dimensions
|
||||
let node_embeddings = gcn.forward(&graph, &features);
|
||||
```
|
||||
|
||||
**Use Cases**: Node classification, link prediction, graph classification
|
||||
|
||||
---
|
||||
|
||||
## ruvector-mincut Bindings
|
||||
|
||||
### ruvector-mincut-wasm
|
||||
**Browser and Edge Deployment**
|
||||
|
||||
Compile min-cut algorithms to WebAssembly for client-side execution.
|
||||
|
||||
```javascript
|
||||
import init, { Graph, karger_min_cut } from 'ruvector-mincut-wasm';
|
||||
|
||||
await init();
|
||||
const graph = new Graph();
|
||||
graph.add_edge(0, 1, 1.0);
|
||||
graph.add_edge(1, 2, 1.0);
|
||||
graph.add_edge(2, 0, 1.0);
|
||||
|
||||
const result = karger_min_cut(graph, 1000);
|
||||
console.log('Min cut:', result.cut_value);
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Zero-copy data transfer
|
||||
- TypeScript definitions
|
||||
- Compatible with all major browsers
|
||||
- Cloudflare Workers, Deno Deploy support
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
npm install ruvector-mincut-wasm
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ruvector-mincut-node
|
||||
**Node.js Native Addon**
|
||||
|
||||
Native Node.js bindings using N-API for maximum performance.
|
||||
|
||||
```javascript
|
||||
const { Graph, kargerMinCut } = require('ruvector-mincut-node');
|
||||
|
||||
const graph = new Graph();
|
||||
graph.addEdge(0, 1, 1.0);
|
||||
graph.addEdge(1, 2, 1.0);
|
||||
|
||||
const result = kargerMinCut(graph, { iterations: 1000 });
|
||||
console.log('Cut value:', result.cutValue);
|
||||
console.log('Partition:', result.partition);
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Native performance (C++ speeds)
|
||||
- Async support with Tokio
|
||||
- Stream processing
|
||||
- Cross-platform (Linux, macOS, Windows)
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
npm install ruvector-mincut-node
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Midstream Integration
|
||||
|
||||
**Midstream** is ruv.io's low-latency streaming platform for real-time data processing.
|
||||
|
||||
### Real-Time Graph Updates
|
||||
|
||||
Process streaming graph updates and maintain min-cut information dynamically.
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::incremental::IncrementalMinCut;
|
||||
use midstream::{Stream, StreamProcessor};
|
||||
|
||||
struct MinCutProcessor {
|
||||
min_cut: IncrementalMinCut,
|
||||
}
|
||||
|
||||
impl StreamProcessor for MinCutProcessor {
|
||||
type Input = GraphUpdate;
|
||||
type Output = CutMetrics;
|
||||
|
||||
fn process(&mut self, update: GraphUpdate) -> CutMetrics {
|
||||
match update {
|
||||
GraphUpdate::AddEdge(u, v, w) => {
|
||||
self.min_cut.add_edge(u, v, w);
|
||||
}
|
||||
GraphUpdate::RemoveEdge(u, v) => {
|
||||
self.min_cut.remove_edge(u, v);
|
||||
}
|
||||
}
|
||||
|
||||
CutMetrics {
|
||||
current_min_cut: self.min_cut.current_value(),
|
||||
connectivity: self.min_cut.edge_connectivity(),
|
||||
timestamp: SystemTime::now(),
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Event Sourcing Patterns
|
||||
|
||||
Store graph mutations as events for replay and analysis.
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::Graph;
|
||||
use serde::{Serialize, Deserialize};
|
||||
|
||||
#[derive(Serialize, Deserialize)]
|
||||
enum GraphEvent {
|
||||
EdgeAdded { u: u32, v: u32, weight: f64, timestamp: u64 },
|
||||
EdgeRemoved { u: u32, v: u32, timestamp: u64 },
|
||||
WeightUpdated { u: u32, v: u32, new_weight: f64, timestamp: u64 },
|
||||
}
|
||||
|
||||
fn replay_events(events: &[GraphEvent]) -> Graph {
|
||||
let mut graph = Graph::new();
|
||||
|
||||
for event in events {
|
||||
match event {
|
||||
GraphEvent::EdgeAdded { u, v, weight, .. } => {
|
||||
graph.add_edge(*u, *v, *weight);
|
||||
}
|
||||
GraphEvent::EdgeRemoved { u, v, .. } => {
|
||||
graph.remove_edge(*u, *v);
|
||||
}
|
||||
GraphEvent::WeightUpdated { u, v, new_weight, .. } => {
|
||||
graph.update_edge_weight(*u, *v, *new_weight);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
graph
|
||||
}
|
||||
```
|
||||
|
||||
### Streaming Analytics
|
||||
|
||||
Combine with Midstream for continuous analytics pipelines.
|
||||
|
||||
```rust
|
||||
// Windowed min-cut analysis
|
||||
let stream = midstream::connect("graph-updates")
|
||||
.window(Duration::from_secs(60))
|
||||
.map(|window| {
|
||||
let graph = build_graph_from_window(window);
|
||||
let (cut_value, partition) = karger_min_cut(&graph, 1000);
|
||||
|
||||
AnalyticsResult {
|
||||
window_start: window.start_time,
|
||||
window_end: window.end_time,
|
||||
min_cut: cut_value,
|
||||
largest_component: partition.largest_size(),
|
||||
}
|
||||
})
|
||||
.into_stream();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Integrations
|
||||
|
||||
### Combining with GNN for Learned Cut Prediction
|
||||
|
||||
Use Graph Neural Networks to predict good cuts before running expensive algorithms.
|
||||
|
||||
```rust
|
||||
use ruvector_gnn::{GCNLayer, GraphConvolution};
|
||||
use ruvector_mincut::{Graph, stoer_wagner};
|
||||
|
||||
struct LearnedCutPredictor {
|
||||
gcn: GCNLayer,
|
||||
}
|
||||
|
||||
impl LearnedCutPredictor {
|
||||
/// Predict edge importance for cutting
|
||||
fn predict_edge_scores(&self, graph: &Graph) -> Vec<f64> {
|
||||
// Extract graph features
|
||||
let features = extract_node_features(graph);
|
||||
|
||||
// Run GNN
|
||||
let embeddings = self.gcn.forward(graph, &features);
|
||||
|
||||
// Compute edge scores from node embeddings
|
||||
compute_edge_scores(graph, &embeddings)
|
||||
}
|
||||
|
||||
/// Use learned scores to guide min-cut search
|
||||
fn guided_min_cut(&self, graph: &Graph) -> (f64, Vec<u32>) {
|
||||
let edge_scores = self.predict_edge_scores(graph);
|
||||
|
||||
// Weight edges by predicted importance
|
||||
let weighted_graph = graph.with_edge_weights(&edge_scores);
|
||||
|
||||
// Run min-cut on weighted graph
|
||||
stoer_wagner(&weighted_graph)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Faster convergence for large graphs
|
||||
- Learn domain-specific patterns
|
||||
- Reduce computational cost by 10-100x
|
||||
|
||||
---
|
||||
|
||||
### Vector Similarity for Edge Weighting
|
||||
|
||||
Use vector embeddings to compute semantic edge weights.
|
||||
|
||||
```rust
|
||||
use ruvector_core::{SimdVector, Distance};
|
||||
use ruvector_index::HnswIndex;
|
||||
use ruvector_mincut::Graph;
|
||||
|
||||
fn build_similarity_graph(
|
||||
embeddings: &[Vec<f32>],
|
||||
k: usize, // k-nearest neighbors
|
||||
threshold: f64,
|
||||
) -> Graph {
|
||||
let mut index = HnswIndex::new(IndexConfig::default());
|
||||
|
||||
// Index all embeddings
|
||||
for (i, emb) in embeddings.iter().enumerate() {
|
||||
index.add(i as u32, emb);
|
||||
}
|
||||
|
||||
let mut graph = Graph::new();
|
||||
|
||||
// Connect k-nearest neighbors
|
||||
for (i, emb) in embeddings.iter().enumerate() {
|
||||
let neighbors = index.search(emb, k);
|
||||
|
||||
for (j, distance) in neighbors {
|
||||
if distance < threshold {
|
||||
// Convert distance to similarity weight
|
||||
let weight = 1.0 / (1.0 + distance);
|
||||
graph.add_edge(i as u32, j, weight);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
graph
|
||||
}
|
||||
```
|
||||
|
||||
**Use Cases:**
|
||||
- Document clustering
|
||||
- Image segmentation
|
||||
- Recommendation systems
|
||||
|
||||
---
|
||||
|
||||
### Attention-Weighted Graphs
|
||||
|
||||
Use attention scores to create dynamic graph structures.
|
||||
|
||||
```rust
|
||||
use ruvector_attention::{MultiHeadAttention, AttentionConfig};
|
||||
use ruvector_mincut::Graph;
|
||||
|
||||
fn attention_to_graph(
|
||||
nodes: &[Vec<f32>],
|
||||
attention_heads: usize,
|
||||
) -> Graph {
|
||||
let dim = nodes[0].len();
|
||||
let config = AttentionConfig::new(dim, attention_heads);
|
||||
let mha = MultiHeadAttention::new(config);
|
||||
|
||||
// Compute attention weights
|
||||
let attention_weights = mha.compute_attention_weights(nodes, nodes);
|
||||
|
||||
// Build graph from attention
|
||||
let mut graph = Graph::new();
|
||||
|
||||
for (i, weights) in attention_weights.iter().enumerate() {
|
||||
for (j, &weight) in weights.iter().enumerate() {
|
||||
if i != j && weight > 0.1 { // Threshold
|
||||
graph.add_edge(i as u32, j as u32, weight);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
graph
|
||||
}
|
||||
```
|
||||
|
||||
**Applications:**
|
||||
- Transformer attention analysis
|
||||
- Neural architecture search
|
||||
- Interpretability studies
|
||||
|
||||
---
|
||||
|
||||
### Multi-Modal Graph Analysis
|
||||
|
||||
Combine multiple RuVector crates for comprehensive analysis.
|
||||
|
||||
```rust
|
||||
use ruvector_graph::Graph as PropertyGraph;
|
||||
use ruvector_index::HnswIndex;
|
||||
use ruvector_mincut::{Graph as MinCutGraph, hierarchical_partition};
|
||||
use ruvector_gnn::GCNLayer;
|
||||
|
||||
struct MultiModalAnalyzer {
|
||||
property_graph: PropertyGraph,
|
||||
vector_index: HnswIndex,
|
||||
gnn: GCNLayer,
|
||||
}
|
||||
|
||||
impl MultiModalAnalyzer {
|
||||
fn analyze(&self) -> AnalysisResult {
|
||||
// 1. Extract topology for min-cut
|
||||
let topology = self.property_graph.to_topology();
|
||||
let mincut_graph = MinCutGraph::from_edges(&topology.edges);
|
||||
|
||||
// 2. Hierarchical partitioning
|
||||
let hierarchy = hierarchical_partition(&mincut_graph, 4);
|
||||
|
||||
// 3. For each partition, run GNN
|
||||
let mut partition_embeddings = Vec::new();
|
||||
|
||||
for partition in hierarchy.partitions {
|
||||
let subgraph = self.property_graph.subgraph(&partition);
|
||||
let features = extract_features(&subgraph);
|
||||
let embeddings = self.gnn.forward(&subgraph, &features);
|
||||
partition_embeddings.push(embeddings);
|
||||
}
|
||||
|
||||
// 4. Index partition representatives
|
||||
for (i, emb) in partition_embeddings.iter().enumerate() {
|
||||
self.vector_index.add(i as u32, &emb.mean());
|
||||
}
|
||||
|
||||
AnalysisResult {
|
||||
hierarchy,
|
||||
embeddings: partition_embeddings,
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ruv.io Platform
|
||||
|
||||
The ruv.io platform provides cloud services and infrastructure for deploying RuVector applications.
|
||||
|
||||
### Cloud Deployment Options
|
||||
|
||||
#### Serverless Functions
|
||||
Deploy min-cut algorithms as serverless functions.
|
||||
|
||||
```yaml
|
||||
# ruv.yml
|
||||
service: graph-analytics
|
||||
runtime: rust
|
||||
memory: 2048
|
||||
|
||||
functions:
|
||||
compute-mincut:
|
||||
handler: ruvector_mincut::handler
|
||||
timeout: 30
|
||||
events:
|
||||
- http:
|
||||
path: /mincut
|
||||
method: post
|
||||
```
|
||||
|
||||
#### Managed Graph Database
|
||||
Use ruv.io's managed graph database with built-in min-cut support.
|
||||
|
||||
```rust
|
||||
use ruvio_client::{GraphClient, MinCutOptions};
|
||||
|
||||
let client = GraphClient::connect("https://api.ruv.io").await?;
|
||||
|
||||
// Upload graph
|
||||
client.create_graph("my-network").await?;
|
||||
client.batch_add_edges("my-network", &edges).await?;
|
||||
|
||||
// Compute min-cut in cloud
|
||||
let result = client.compute_mincut("my-network", MinCutOptions {
|
||||
algorithm: "stoer-wagner",
|
||||
iterations: 1000,
|
||||
}).await?;
|
||||
```
|
||||
|
||||
#### API Services
|
||||
|
||||
**REST API:**
|
||||
```bash
|
||||
curl -X POST https://api.ruv.io/v1/mincut \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"graph": {
|
||||
"edges": [[0, 1, 1.0], [1, 2, 1.0], [2, 0, 1.0]]
|
||||
},
|
||||
"algorithm": "karger",
|
||||
"iterations": 1000
|
||||
}'
|
||||
```
|
||||
|
||||
**GraphQL API:**
|
||||
```graphql
|
||||
mutation ComputeMinCut {
|
||||
computeMinCut(
|
||||
graphId: "my-network"
|
||||
algorithm: STOER_WAGNER
|
||||
) {
|
||||
cutValue
|
||||
partition {
|
||||
setA
|
||||
setB
|
||||
}
|
||||
executionTime
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Infrastructure Features
|
||||
|
||||
- **Auto-scaling**: Handle traffic spikes automatically
|
||||
- **Global CDN**: Low-latency access worldwide
|
||||
- **Monitoring**: Built-in metrics and tracing
|
||||
- **High Availability**: 99.99% uptime SLA
|
||||
- **Security**: SOC 2 Type II, GDPR compliant
|
||||
|
||||
### Documentation & Support
|
||||
|
||||
- **API Documentation**: https://ruv.io/docs/api
|
||||
- **Tutorials**: https://ruv.io/tutorials
|
||||
- **Community Forum**: https://community.ruv.io
|
||||
- **Enterprise Support**: support@ruv.io
|
||||
|
||||
---
|
||||
|
||||
## Ecosystem Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Core Layer"
|
||||
CORE[ruvector-core<br/>SIMD Primitives]
|
||||
end
|
||||
|
||||
subgraph "Data Structures"
|
||||
GRAPH[ruvector-graph<br/>Property Graph]
|
||||
INDEX[ruvector-index<br/>Vector Index]
|
||||
MINCUT[ruvector-mincut<br/>Graph Partitioning]
|
||||
end
|
||||
|
||||
subgraph "ML Layer"
|
||||
ATTENTION[ruvector-attention<br/>Transformers]
|
||||
GNN[ruvector-gnn<br/>Graph Neural Networks]
|
||||
end
|
||||
|
||||
subgraph "Bindings"
|
||||
WASM[ruvector-mincut-wasm<br/>Browser]
|
||||
NODE[ruvector-mincut-node<br/>Node.js]
|
||||
end
|
||||
|
||||
subgraph "Platform"
|
||||
MIDSTREAM[Midstream<br/>Streaming]
|
||||
RUVIO[ruv.io<br/>Cloud Platform]
|
||||
end
|
||||
|
||||
subgraph "Applications"
|
||||
WEB[Web Apps]
|
||||
SERVER[Server Apps]
|
||||
CLOUD[Cloud Services]
|
||||
end
|
||||
|
||||
CORE --> GRAPH
|
||||
CORE --> INDEX
|
||||
CORE --> MINCUT
|
||||
CORE --> ATTENTION
|
||||
CORE --> GNN
|
||||
|
||||
GRAPH --> MINCUT
|
||||
INDEX --> GRAPH
|
||||
GNN --> GRAPH
|
||||
ATTENTION --> GNN
|
||||
|
||||
MINCUT --> WASM
|
||||
MINCUT --> NODE
|
||||
MINCUT --> MIDSTREAM
|
||||
|
||||
WASM --> WEB
|
||||
NODE --> SERVER
|
||||
MIDSTREAM --> CLOUD
|
||||
MINCUT --> RUVIO
|
||||
GRAPH --> RUVIO
|
||||
INDEX --> RUVIO
|
||||
|
||||
style MINCUT fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px
|
||||
style CORE fill:#4dabf7,stroke:#1971c2,stroke-width:2px
|
||||
style RUVIO fill:#51cf66,stroke:#2f9e44,stroke-width:2px
|
||||
```
|
||||
|
||||
### Data Flow Example
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as Application
|
||||
participant Index as ruvector-index
|
||||
participant Graph as ruvector-graph
|
||||
participant MinCut as ruvector-mincut
|
||||
participant GNN as ruvector-gnn
|
||||
participant Platform as ruv.io
|
||||
|
||||
App->>Index: Query similar nodes
|
||||
Index-->>App: k-nearest neighbors
|
||||
|
||||
App->>Graph: Build subgraph
|
||||
Graph->>MinCut: Extract topology
|
||||
MinCut-->>Graph: Partition graph
|
||||
|
||||
Graph->>GNN: Train on partitions
|
||||
GNN-->>App: Node embeddings
|
||||
|
||||
App->>Platform: Deploy model
|
||||
Platform-->>App: Inference endpoint
|
||||
```
|
||||
|
||||
### Deployment Options
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Development"
|
||||
DEV[Local Development]
|
||||
end
|
||||
|
||||
subgraph "Edge"
|
||||
BROWSER[Browser<br/>WASM]
|
||||
EDGE[Edge Workers<br/>WASM]
|
||||
end
|
||||
|
||||
subgraph "Server"
|
||||
NODEJS[Node.js<br/>Native]
|
||||
RUST[Rust Service<br/>Native]
|
||||
end
|
||||
|
||||
subgraph "Cloud"
|
||||
LAMBDA[Serverless<br/>ruv.io]
|
||||
MANAGED[Managed Service<br/>ruv.io]
|
||||
end
|
||||
|
||||
DEV --> BROWSER
|
||||
DEV --> EDGE
|
||||
DEV --> NODEJS
|
||||
DEV --> RUST
|
||||
DEV --> LAMBDA
|
||||
DEV --> MANAGED
|
||||
|
||||
style DEV fill:#fab005,stroke:#f08c00
|
||||
style BROWSER fill:#4dabf7,stroke:#1971c2
|
||||
style EDGE fill:#4dabf7,stroke:#1971c2
|
||||
style NODEJS fill:#51cf66,stroke:#2f9e44
|
||||
style RUST fill:#51cf66,stroke:#2f9e44
|
||||
style LAMBDA fill:#ff6b6b,stroke:#c92a2a
|
||||
style MANAGED fill:#ff6b6b,stroke:#c92a2a
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
### Official Links
|
||||
|
||||
- **Website**: [ruv.io](https://ruv.io)
|
||||
- **GitHub Organization**: [github.com/ruvnet](https://github.com/ruvnet)
|
||||
- **Main Repository**: [github.com/ruvnet/ruvector](https://github.com/ruvnet/ruvector)
|
||||
|
||||
### Crates.io Pages
|
||||
|
||||
- [ruvector-core](https://crates.io/crates/ruvector-core)
|
||||
- [ruvector-graph](https://crates.io/crates/ruvector-graph)
|
||||
- [ruvector-index](https://crates.io/crates/ruvector-index)
|
||||
- [ruvector-mincut](https://crates.io/crates/ruvector-mincut)
|
||||
- [ruvector-attention](https://crates.io/crates/ruvector-attention)
|
||||
- [ruvector-gnn](https://crates.io/crates/ruvector-gnn)
|
||||
|
||||
### NPM Packages
|
||||
|
||||
- [ruvector-mincut-wasm](https://www.npmjs.com/package/ruvector-mincut-wasm)
|
||||
- [ruvector-mincut-node](https://www.npmjs.com/package/ruvector-mincut-node)
|
||||
|
||||
### Documentation
|
||||
|
||||
- **API Docs**: [docs.ruv.io](https://docs.ruv.io)
|
||||
- **Tutorials**: [ruv.io/tutorials](https://ruv.io/tutorials)
|
||||
- **Examples**: [github.com/ruvnet/ruvector/tree/main/examples](https://github.com/ruvnet/ruvector/tree/main/examples)
|
||||
|
||||
### Community
|
||||
|
||||
- **Discord**: [discord.gg/ruvector](https://discord.gg/ruvector)
|
||||
- **Forum**: [community.ruv.io](https://community.ruv.io)
|
||||
- **Twitter**: [@ruvnet](https://twitter.com/ruvnet)
|
||||
- **Blog**: [ruv.io/blog](https://ruv.io/blog)
|
||||
|
||||
### Support
|
||||
|
||||
- **Issues**: [github.com/ruvnet/ruvector/issues](https://github.com/ruvnet/ruvector/issues)
|
||||
- **Discussions**: [github.com/ruvnet/ruvector/discussions](https://github.com/ruvnet/ruvector/discussions)
|
||||
- **Enterprise Support**: enterprise@ruv.io
|
||||
- **Security Issues**: security@ruv.io
|
||||
|
||||
---
|
||||
|
||||
## Getting Started with the Ecosystem
|
||||
|
||||
### 1. Start with Core
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
ruvector-core = "0.1"
|
||||
```
|
||||
|
||||
```rust
|
||||
use ruvector_core::SimdVector;
|
||||
|
||||
let vec = SimdVector::from_slice(&[1.0, 2.0, 3.0, 4.0]);
|
||||
```
|
||||
|
||||
### 2. Add Graph Capabilities
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
ruvector-core = "0.1"
|
||||
ruvector-graph = "0.1"
|
||||
ruvector-mincut = "0.1"
|
||||
```
|
||||
|
||||
```rust
|
||||
use ruvector_graph::Graph;
|
||||
use ruvector_mincut::karger_min_cut;
|
||||
|
||||
let graph = Graph::from_edges(&[(0, 1), (1, 2), (2, 0)]);
|
||||
let (cut, partition) = karger_min_cut(&graph, 1000);
|
||||
```
|
||||
|
||||
### 3. Add ML Features
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
ruvector-core = "0.1"
|
||||
ruvector-graph = "0.1"
|
||||
ruvector-gnn = "0.1"
|
||||
```
|
||||
|
||||
```rust
|
||||
use ruvector_gnn::GCNLayer;
|
||||
|
||||
let gcn = GCNLayer::new(128, 64);
|
||||
let embeddings = gcn.forward(&graph, &features);
|
||||
```
|
||||
|
||||
### 4. Deploy to Cloud
|
||||
|
||||
```bash
|
||||
# Install ruv.io CLI
|
||||
cargo install ruvio-cli
|
||||
|
||||
# Login
|
||||
ruvio login
|
||||
|
||||
# Deploy
|
||||
ruvio deploy --service graph-analytics
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Explore Examples**: Check out the [examples directory](https://github.com/ruvnet/ruvector/tree/main/examples)
|
||||
- **Join Community**: Connect with other developers on [Discord](https://discord.gg/ruvector)
|
||||
- **Read Tutorials**: Learn patterns at [ruv.io/tutorials](https://ruv.io/tutorials)
|
||||
- **Try Cloud**: Sign up for [ruv.io platform](https://ruv.io/signup)
|
||||
|
||||
---
|
||||
|
||||
**The RuVector ecosystem provides everything you need to build high-performance graph and vector applications, from edge to cloud.**
|
||||
1037
vendor/ruvector/crates/ruvector-mincut/docs/guide/07-api-reference.md
vendored
Normal file
1037
vendor/ruvector/crates/ruvector-mincut/docs/guide/07-api-reference.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
559
vendor/ruvector/crates/ruvector-mincut/docs/guide/08-troubleshooting.md
vendored
Normal file
559
vendor/ruvector/crates/ruvector-mincut/docs/guide/08-troubleshooting.md
vendored
Normal file
@@ -0,0 +1,559 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
[← Back to Index](README.md) | [Previous: API Reference](07-api-reference.md)
|
||||
|
||||
---
|
||||
|
||||
## Quick Diagnosis Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Issue Encountered] --> B{Type of Issue?}
|
||||
|
||||
B -->|Compilation| C[Compilation Errors]
|
||||
B -->|Runtime| D[Runtime Errors]
|
||||
B -->|Performance| E[Performance Issues]
|
||||
B -->|Results| F[Unexpected Results]
|
||||
|
||||
C --> C1[Check feature flags]
|
||||
C --> C2[Version compatibility]
|
||||
C --> C3[Missing dependencies]
|
||||
|
||||
D --> D1[Memory issues]
|
||||
D --> D2[Edge not found]
|
||||
D --> D3[Graph disconnected]
|
||||
|
||||
E --> E1[Algorithm selection]
|
||||
E --> E2[Graph size tuning]
|
||||
E --> E3[Caching strategies]
|
||||
|
||||
F --> F1[Verify graph construction]
|
||||
F --> F2[Check edge weights]
|
||||
F --> F3[Understand approximation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. Compilation Errors
|
||||
|
||||
### Feature Flag Issues
|
||||
|
||||
**Error**: `use of undeclared type MonitorBuilder`
|
||||
|
||||
```
|
||||
error[E0433]: failed to resolve: use of undeclared type `MonitorBuilder`
|
||||
```
|
||||
|
||||
**Solution**: Enable the `monitoring` feature:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
ruvector-mincut = { version = "0.2", features = ["monitoring"] }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Error**: `use of undeclared type CompactCoreState`
|
||||
|
||||
**Solution**: Enable the `agentic` feature:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
ruvector-mincut = { version = "0.2", features = ["agentic"] }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Feature Flag Reference
|
||||
|
||||
| Type/Feature | Required Feature Flag |
|
||||
|--------------|----------------------|
|
||||
| `MonitorBuilder`, `MinCutMonitor` | `monitoring` |
|
||||
| `CompactCoreState`, `BitSet256` | `agentic` |
|
||||
| `SparseGraph` | `approximate` |
|
||||
| SIMD optimizations | `simd` |
|
||||
| WASM support | `wasm` |
|
||||
|
||||
### Version Compatibility
|
||||
|
||||
**Error**: `the trait bound is not satisfied`
|
||||
|
||||
Check your dependency versions are compatible:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
ruvector-mincut = "0.2"
|
||||
ruvector-core = "0.1.2" # Must be compatible
|
||||
ruvector-graph = "0.1.2" # If using integration feature
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Runtime Errors
|
||||
|
||||
### EdgeExists Error
|
||||
|
||||
**Error**: `EdgeExists(1, 2)` when inserting an edge
|
||||
|
||||
```rust
|
||||
// ❌ This will fail - edge already exists
|
||||
mincut.insert_edge(1, 2, 1.0)?;
|
||||
mincut.insert_edge(1, 2, 2.0)?; // Error!
|
||||
```
|
||||
|
||||
**Solution**: Check if edge exists first, or delete before reinserting:
|
||||
|
||||
```rust
|
||||
// ✅ Option 1: Delete first
|
||||
let _ = mincut.delete_edge(1, 2); // Ignore if not found
|
||||
mincut.insert_edge(1, 2, 2.0)?;
|
||||
|
||||
// ✅ Option 2: Check existence (if your API supports it)
|
||||
if !mincut.has_edge(1, 2) {
|
||||
mincut.insert_edge(1, 2, 1.0)?;
|
||||
}
|
||||
```
|
||||
|
||||
### EdgeNotFound Error
|
||||
|
||||
**Error**: `EdgeNotFound(3, 4)` when deleting
|
||||
|
||||
```rust
|
||||
// ❌ Edge doesn't exist
|
||||
mincut.delete_edge(3, 4)?; // Error!
|
||||
```
|
||||
|
||||
**Solution**: Use pattern matching to handle gracefully:
|
||||
|
||||
```rust
|
||||
// ✅ Handle gracefully
|
||||
match mincut.delete_edge(3, 4) {
|
||||
Ok(new_cut) => println!("New min cut: {}", new_cut),
|
||||
Err(MinCutError::EdgeNotFound(_, _)) => {
|
||||
println!("Edge already removed, continuing...");
|
||||
}
|
||||
Err(e) => return Err(e.into()),
|
||||
}
|
||||
```
|
||||
|
||||
### Disconnected Graph
|
||||
|
||||
**Issue**: Min cut value is 0
|
||||
|
||||
```rust
|
||||
let mincut = MinCutBuilder::new()
|
||||
.with_edges(vec![
|
||||
(1, 2, 1.0),
|
||||
(3, 4, 1.0), // Separate component!
|
||||
])
|
||||
.build()?;
|
||||
|
||||
assert_eq!(mincut.min_cut_value(), 0.0); // Zero because disconnected
|
||||
```
|
||||
|
||||
**Solution**: Ensure your graph is connected, or handle disconnected case:
|
||||
|
||||
```rust
|
||||
if !mincut.is_connected() {
|
||||
println!("Warning: Graph has {} components",
|
||||
mincut.component_count());
|
||||
// Handle each component separately
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Performance Issues
|
||||
|
||||
### Slow Insert/Delete Operations
|
||||
|
||||
**Symptom**: Operations taking longer than expected
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Slow Operations] --> B{Check Graph Size}
|
||||
B -->|< 10K vertices| C[Normal - check algorithm]
|
||||
B -->|10K-100K| D[Consider approximate mode]
|
||||
B -->|> 100K| E[Use ApproxMinCut]
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Use approximate mode for large graphs**:
|
||||
```rust
|
||||
// Instead of exact mode
|
||||
let mincut = MinCutBuilder::new()
|
||||
.approximate(0.1) // 10% approximation
|
||||
.with_edges(edges)
|
||||
.build()?;
|
||||
```
|
||||
|
||||
2. **Use batch operations**:
|
||||
```rust
|
||||
// ❌ Slow - many individual operations
|
||||
for (u, v, w) in edges {
|
||||
mincut.insert_edge(u, v, w)?;
|
||||
}
|
||||
|
||||
// ✅ Fast - batch operation
|
||||
mincut.batch_insert_edges(&edges);
|
||||
```
|
||||
|
||||
3. **For worst-case guarantees, use PolylogConnectivity**:
|
||||
```rust
|
||||
// O(log³ n) worst-case per operation
|
||||
let mut conn = PolylogConnectivity::new();
|
||||
for (u, v) in edges {
|
||||
conn.insert_edge(u, v);
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Issues
|
||||
|
||||
**Symptom**: High memory usage or OOM errors
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Use approximate mode** (reduces edges via sparsification):
|
||||
```rust
|
||||
let mincut = MinCutBuilder::new()
|
||||
.approximate(0.1) // Sparsifies to O(n log n / ε²) edges
|
||||
.build()?;
|
||||
```
|
||||
|
||||
2. **For WASM/embedded, use compact structures**:
|
||||
```rust
|
||||
#[cfg(feature = "agentic")]
|
||||
{
|
||||
// 6.7KB per core - verified at compile time
|
||||
let state = CompactCoreState::new();
|
||||
}
|
||||
```
|
||||
|
||||
3. **Process in batches for very large graphs**:
|
||||
```rust
|
||||
// Process graph in chunks
|
||||
for chunk in graph_chunks.iter() {
|
||||
let partial = MinCutBuilder::new()
|
||||
.with_edges(chunk)
|
||||
.build()?;
|
||||
// Aggregate results
|
||||
}
|
||||
```
|
||||
|
||||
### Query Performance
|
||||
|
||||
**Symptom**: `min_cut_value()` is slow
|
||||
|
||||
**Explanation**: First query triggers computation; subsequent queries are O(1):
|
||||
|
||||
```rust
|
||||
let mincut = MinCutBuilder::new()
|
||||
.with_edges(edges)
|
||||
.build()?;
|
||||
|
||||
// First query - triggers full computation
|
||||
let cut1 = mincut.min_cut_value(); // May take time
|
||||
|
||||
// Subsequent queries - O(1) cached
|
||||
let cut2 = mincut.min_cut_value(); // Instant
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Unexpected Results
|
||||
|
||||
### Min Cut Value Seems Wrong
|
||||
|
||||
**Checklist**:
|
||||
|
||||
1. **Verify edge weights are correct**:
|
||||
```rust
|
||||
// Weight matters! This is different from weight 1.0
|
||||
mincut.insert_edge(1, 2, 10.0)?;
|
||||
```
|
||||
|
||||
2. **Check for duplicate edges** (weights accumulate):
|
||||
```rust
|
||||
// These DON'T accumulate - second insert fails
|
||||
mincut.insert_edge(1, 2, 5.0)?;
|
||||
mincut.insert_edge(1, 2, 5.0)?; // Error: EdgeExists
|
||||
```
|
||||
|
||||
3. **Understand the cut definition**:
|
||||
```rust
|
||||
// Min cut = minimum total weight of edges to remove
|
||||
// to disconnect the graph
|
||||
let result = mincut.min_cut();
|
||||
println!("Cut value: {}", result.value);
|
||||
println!("Cut edges: {:?}", result.cut_edges);
|
||||
```
|
||||
|
||||
### Approximate Results Vary
|
||||
|
||||
**Issue**: Different runs give different results
|
||||
|
||||
**Explanation**: Approximate mode uses randomized sparsification:
|
||||
|
||||
```rust
|
||||
// Results may vary slightly between builds
|
||||
let mincut1 = MinCutBuilder::new()
|
||||
.approximate(0.1)
|
||||
.with_edges(edges.clone())
|
||||
.build()?;
|
||||
|
||||
let mincut2 = MinCutBuilder::new()
|
||||
.approximate(0.1)
|
||||
.with_edges(edges)
|
||||
.build()?;
|
||||
|
||||
// Values are within (1±ε) of true min cut
|
||||
// but may differ from each other
|
||||
```
|
||||
|
||||
**Solution**: Use a fixed seed if reproducibility is needed:
|
||||
|
||||
```rust
|
||||
let approx = ApproxMinCut::new(ApproxMinCutConfig {
|
||||
epsilon: 0.1,
|
||||
num_samples: 3,
|
||||
seed: 42, // Fixed seed for reproducibility
|
||||
});
|
||||
```
|
||||
|
||||
### Partition Looks Unbalanced
|
||||
|
||||
**Issue**: One side of partition has most vertices
|
||||
|
||||
**Explanation**: Minimum cut doesn't guarantee balanced partitions:
|
||||
|
||||
```rust
|
||||
let result = mincut.min_cut();
|
||||
let (s, t) = result.partition.unwrap();
|
||||
|
||||
// This is valid - min cut found the minimum edges to cut
|
||||
// Partition balance is NOT a constraint
|
||||
println!("Partition sizes: {} vs {}", s.len(), t.len());
|
||||
```
|
||||
|
||||
**Solution**: For balanced partitions, use `GraphPartitioner`:
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::GraphPartitioner;
|
||||
|
||||
let partitioner = GraphPartitioner::new(graph, 2);
|
||||
let balanced = partitioner.partition(); // More balanced
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. WASM-Specific Issues
|
||||
|
||||
### WASM Build Fails
|
||||
|
||||
**Error**: `wasm32 target not installed`
|
||||
|
||||
```bash
|
||||
# Install the target
|
||||
rustup target add wasm32-unknown-unknown
|
||||
|
||||
# Build with wasm-pack
|
||||
wasm-pack build --target web
|
||||
```
|
||||
|
||||
### WASM Memory Limits
|
||||
|
||||
**Issue**: WASM running out of memory
|
||||
|
||||
**Solution**: Use compact structures and limit graph size:
|
||||
|
||||
```rust
|
||||
// Maximum recommended for WASM
|
||||
const MAX_WASM_VERTICES: usize = 50_000;
|
||||
|
||||
if vertices.len() > MAX_WASM_VERTICES {
|
||||
// Use approximate mode or process in chunks
|
||||
let mincut = MinCutBuilder::new()
|
||||
.approximate(0.2) // More aggressive sparsification
|
||||
.build()?;
|
||||
}
|
||||
```
|
||||
|
||||
### Web Worker Integration
|
||||
|
||||
**Issue**: Main thread blocking
|
||||
|
||||
**Solution**: Run min-cut computation in Web Worker:
|
||||
|
||||
```javascript
|
||||
// worker.js
|
||||
import init, { WasmMinCut } from 'ruvector-mincut-wasm';
|
||||
|
||||
self.onmessage = async (e) => {
|
||||
await init();
|
||||
const mincut = new WasmMinCut();
|
||||
// ... compute
|
||||
self.postMessage({ result: mincut.min_cut_value() });
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Node.js-Specific Issues
|
||||
|
||||
### Native Module Build Fails
|
||||
|
||||
**Error**: `node-gyp` or `napi` build errors
|
||||
|
||||
```bash
|
||||
# Ensure build tools are installed
|
||||
# On Ubuntu/Debian:
|
||||
sudo apt-get install build-essential
|
||||
|
||||
# On macOS:
|
||||
xcode-select --install
|
||||
|
||||
# On Windows:
|
||||
npm install --global windows-build-tools
|
||||
```
|
||||
|
||||
### Module Not Found
|
||||
|
||||
**Error**: `Cannot find module 'ruvector-mincut-node'`
|
||||
|
||||
```bash
|
||||
# Rebuild native modules
|
||||
npm rebuild
|
||||
|
||||
# Or reinstall
|
||||
rm -rf node_modules
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Common Patterns That Cause Issues
|
||||
|
||||
### Anti-Pattern: Not Handling Errors
|
||||
|
||||
```rust
|
||||
// ❌ Panics on error
|
||||
let cut = mincut.insert_edge(1, 2, 1.0).unwrap();
|
||||
|
||||
// ✅ Handle errors properly
|
||||
let cut = mincut.insert_edge(1, 2, 1.0)
|
||||
.map_err(|e| {
|
||||
eprintln!("Insert failed: {}", e);
|
||||
e
|
||||
})?;
|
||||
```
|
||||
|
||||
### Anti-Pattern: Rebuilding Instead of Updating
|
||||
|
||||
```rust
|
||||
// ❌ Slow - rebuilds entire structure
|
||||
for update in updates {
|
||||
let mincut = MinCutBuilder::new()
|
||||
.with_edges(all_edges_including_update)
|
||||
.build()?;
|
||||
}
|
||||
|
||||
// ✅ Fast - incremental updates
|
||||
let mut mincut = MinCutBuilder::new()
|
||||
.with_edges(initial_edges)
|
||||
.build()?;
|
||||
|
||||
for (u, v, w) in updates {
|
||||
mincut.insert_edge(u, v, w)?;
|
||||
}
|
||||
```
|
||||
|
||||
### Anti-Pattern: Ignoring Feature Requirements
|
||||
|
||||
```rust
|
||||
// ❌ Compiles but panics at runtime if feature not enabled
|
||||
#[cfg(feature = "monitoring")]
|
||||
let monitor = MonitorBuilder::new().build();
|
||||
|
||||
// ✅ Proper feature gating
|
||||
#[cfg(feature = "monitoring")]
|
||||
{
|
||||
let monitor = MonitorBuilder::new().build();
|
||||
// Use monitor
|
||||
}
|
||||
#[cfg(not(feature = "monitoring"))]
|
||||
{
|
||||
println!("Monitoring not available - enable 'monitoring' feature");
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Getting Help
|
||||
|
||||
### Debug Information
|
||||
|
||||
When reporting issues, include:
|
||||
|
||||
```rust
|
||||
// Print diagnostic info
|
||||
println!("ruvector-mincut version: {}", ruvector_mincut::VERSION);
|
||||
println!("Graph: {} vertices, {} edges",
|
||||
mincut.num_vertices(),
|
||||
mincut.num_edges());
|
||||
println!("Algorithm stats: {:?}", mincut.stats());
|
||||
```
|
||||
|
||||
### Resources
|
||||
|
||||
| Resource | URL |
|
||||
|----------|-----|
|
||||
| GitHub Issues | [github.com/ruvnet/ruvector/issues](https://github.com/ruvnet/ruvector/issues) |
|
||||
| Documentation | [docs.rs/ruvector-mincut](https://docs.rs/ruvector-mincut) |
|
||||
| Discord | [ruv.io/discord](https://ruv.io/discord) |
|
||||
| Stack Overflow | Tag: `ruvector` |
|
||||
|
||||
### Minimal Reproducible Example
|
||||
|
||||
When reporting bugs, provide:
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::{MinCutBuilder, MinCutError};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
// Minimal code that reproduces the issue
|
||||
let mincut = MinCutBuilder::new()
|
||||
.with_edges(vec![
|
||||
// Your specific edges
|
||||
])
|
||||
.build()?;
|
||||
|
||||
// The operation that fails
|
||||
let result = mincut.min_cut_value();
|
||||
|
||||
println!("Result: {}", result);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Error Codes
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| `EdgeExists(u, v)` | Duplicate edge insertion | Delete first or check existence |
|
||||
| `EdgeNotFound(u, v)` | Deleting non-existent edge | Use pattern matching |
|
||||
| `InvalidWeight` | Zero or negative weight | Use positive weights |
|
||||
| `GraphTooLarge` | Exceeds memory limits | Use approximate mode |
|
||||
| `NotConnected` | Graph has multiple components | Check connectivity first |
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**Still stuck?** [Open an issue](https://github.com/ruvnet/ruvector/issues/new) with your code and error message.
|
||||
|
||||
[← Back to Index](README.md)
|
||||
|
||||
</div>
|
||||
313
vendor/ruvector/crates/ruvector-mincut/docs/guide/README.md
vendored
Normal file
313
vendor/ruvector/crates/ruvector-mincut/docs/guide/README.md
vendored
Normal file
@@ -0,0 +1,313 @@
|
||||
# RuVector MinCut User Guide
|
||||
|
||||
<div align="center">
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**High-performance minimum cut algorithms for Rust, WebAssembly, and Node.js**
|
||||
|
||||
[Quick Start](#quick-start) • [Guide Sections](#guide-sections) • [API Reference](07-api-reference.md) • [Benchmarks](../BENCHMARK_REPORT.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Welcome
|
||||
|
||||
Welcome to the official **RuVector MinCut User Guide**! This comprehensive documentation will help you master graph minimum cut algorithms and integrate them into your applications.
|
||||
|
||||
RuVector MinCut provides cutting-edge implementations of minimum cut algorithms from recent research papers (2024-2025), optimized for production use across multiple platforms. Whether you're building network reliability systems, image segmentation tools, or distributed infrastructure, this guide will help you leverage the power of efficient minimum cut computation.
|
||||
|
||||
### What You'll Learn
|
||||
|
||||
- 🚀 **Getting Started**: Installation, setup, and your first minimum cut computation
|
||||
- 🧠 **Core Concepts**: Understanding minimum cuts, connectivity, and algorithm selection
|
||||
- 💼 **Practical Applications**: Real-world use cases from network analysis to ML
|
||||
- 🔧 **Integration**: Platform-specific guides for Rust, WASM, and Node.js
|
||||
- 🎯 **Advanced Examples**: Complex workflows and optimization techniques
|
||||
- 🌐 **Ecosystem**: Leverage the full RuVector platform
|
||||
- 📚 **API Reference**: Complete API documentation
|
||||
- 🔍 **Troubleshooting**: Common issues and solutions
|
||||
|
||||
---
|
||||
|
||||
## Guide Structure
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[RuVector MinCut Guide] --> B[01: Getting Started]
|
||||
A --> C[02: Core Concepts]
|
||||
A --> D[03: Practical Applications]
|
||||
A --> E[04: Integration Guide]
|
||||
A --> F[05: Advanced Examples]
|
||||
A --> G[06: RuVector Ecosystem]
|
||||
A --> H[07: API Reference]
|
||||
A --> I[08: Troubleshooting]
|
||||
|
||||
B --> B1[Installation]
|
||||
B --> B2[Quick Start]
|
||||
B --> B3[First Cut]
|
||||
|
||||
C --> C1[Min Cut Theory]
|
||||
C --> C2[Algorithms]
|
||||
C --> C3[Performance]
|
||||
|
||||
D --> D1[Network Reliability]
|
||||
D --> D2[Image Segmentation]
|
||||
D --> D3[Clustering]
|
||||
|
||||
E --> E1[Rust Integration]
|
||||
E --> E2[WASM Integration]
|
||||
E --> E3[Node.js Integration]
|
||||
|
||||
F --> F1[Custom Workflows]
|
||||
F --> F2[Optimization]
|
||||
F --> F3[Large Graphs]
|
||||
|
||||
G --> G1[Vector Database]
|
||||
G --> G2[QUIC Sync]
|
||||
G --> G3[Platform Tools]
|
||||
|
||||
H --> H1[Rust API]
|
||||
H --> H2[WASM API]
|
||||
H --> H3[Node.js API]
|
||||
|
||||
I --> I1[Common Issues]
|
||||
I --> I2[Performance]
|
||||
I --> I3[Debugging]
|
||||
|
||||
style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
|
||||
style B fill:#50C878,stroke:#2E7D52,stroke-width:2px,color:#fff
|
||||
style C fill:#9B59B6,stroke:#6C3483,stroke-width:2px,color:#fff
|
||||
style D fill:#E67E22,stroke:#A04000,stroke-width:2px,color:#fff
|
||||
style E fill:#3498DB,stroke:#21618C,stroke-width:2px,color:#fff
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
New to RuVector MinCut? Start here:
|
||||
|
||||
1. **[Getting Started Guide](01-getting-started.md)** - Install and run your first minimum cut
|
||||
2. **[Core Concepts](02-core-concepts.md)** - Understand the fundamentals
|
||||
3. **[Integration Guide](04-integration-guide.md)** - Platform-specific setup
|
||||
|
||||
Already familiar? Jump to:
|
||||
- **[Practical Applications](03-practical-applications.md)** - Real-world examples
|
||||
- **[Advanced Examples](05-advanced-examples.md)** - Complex workflows
|
||||
- **[API Reference](07-api-reference.md)** - Complete API documentation
|
||||
|
||||
---
|
||||
|
||||
## Guide Sections
|
||||
|
||||
### 📖 [01: Getting Started](01-getting-started.md)
|
||||
|
||||
Your first steps with RuVector MinCut:
|
||||
- **Installation** - Add to your Rust, WASM, or Node.js project
|
||||
- **Quick Start** - Run your first minimum cut in minutes
|
||||
- **Basic Usage** - Simple examples to get you started
|
||||
- **Platform Setup** - Environment-specific configuration
|
||||
|
||||
**Perfect for**: New users, quick evaluation, proof-of-concept projects
|
||||
|
||||
---
|
||||
|
||||
### 🧠 [02: Core Concepts](02-core-concepts.md)
|
||||
|
||||
Deep dive into minimum cut theory and implementation:
|
||||
- **What is a Minimum Cut?** - Mathematical foundations
|
||||
- **Algorithm Overview** - Karger-Stein, Stoer-Wagner, and cutting-edge variants
|
||||
- **Connectivity Analysis** - Understanding graph structure
|
||||
- **Performance Characteristics** - Algorithm selection guide
|
||||
- **Data Structures** - Internal representations and optimizations
|
||||
|
||||
**Perfect for**: Understanding algorithm behavior, making informed choices, optimization
|
||||
|
||||
---
|
||||
|
||||
### 💼 [03: Practical Applications](03-practical-applications.md)
|
||||
|
||||
Real-world use cases and industry applications:
|
||||
- **Network Reliability** - Finding critical connections and bottlenecks
|
||||
- **Image Segmentation** - Computer vision and ML applications
|
||||
- **Community Detection** - Social network analysis
|
||||
- **Infrastructure Planning** - Cloud and distributed systems
|
||||
- **Data Clustering** - Machine learning and analytics
|
||||
- **Risk Assessment** - Financial and security applications
|
||||
|
||||
**Perfect for**: Industry applications, use case research, project planning
|
||||
|
||||
---
|
||||
|
||||
### 🔧 [04: Integration Guide](04-integration-guide.md)
|
||||
|
||||
Platform-specific integration instructions:
|
||||
- **Rust Integration** - Native library usage, features, and best practices
|
||||
- **WebAssembly** - Browser and edge deployment
|
||||
- **Node.js** - Backend and CLI applications
|
||||
- **TypeScript** - Type-safe JavaScript integration
|
||||
- **Build Configuration** - Optimization and compilation
|
||||
- **Deployment** - Production considerations
|
||||
|
||||
**Perfect for**: Production integration, platform-specific questions, deployment
|
||||
|
||||
---
|
||||
|
||||
### 🎯 [05: Advanced Examples](05-advanced-examples.md)
|
||||
|
||||
Complex workflows and optimization techniques:
|
||||
- **Large Graph Processing** - Handling millions of nodes
|
||||
- **Parallel Computation** - Multi-threaded and distributed processing
|
||||
- **Custom Workflows** - Building on top of MinCut APIs
|
||||
- **Performance Tuning** - Memory and speed optimization
|
||||
- **Hybrid Approaches** - Combining multiple algorithms
|
||||
- **Streaming Analysis** - Real-time graph updates
|
||||
|
||||
**Perfect for**: Performance optimization, large-scale systems, advanced users
|
||||
|
||||
---
|
||||
|
||||
### 🌐 [06: RuVector Ecosystem](06-ecosystem.md)
|
||||
|
||||
Leverage the complete RuVector platform:
|
||||
- **Vector Database Integration** - Combine with ruvector-db
|
||||
- **QUIC Synchronization** - Distributed graph analysis
|
||||
- **Platform Services** - Cloud deployment with ruv.io
|
||||
- **Multi-Language Support** - Cross-platform workflows
|
||||
- **Monitoring & Analytics** - Production observability
|
||||
- **Community & Support** - Resources and help
|
||||
|
||||
**Perfect for**: Platform integration, distributed systems, enterprise deployment
|
||||
|
||||
---
|
||||
|
||||
### 📚 [07: API Reference](07-api-reference.md)
|
||||
|
||||
Complete API documentation:
|
||||
- **Rust API** - Full crate documentation
|
||||
- **WASM API** - JavaScript/TypeScript bindings
|
||||
- **Node.js API** - npm package reference
|
||||
- **Type Definitions** - Complete type signatures
|
||||
- **Error Handling** - Exception types and recovery
|
||||
- **Migration Guide** - Version updates and breaking changes
|
||||
|
||||
**Perfect for**: API lookup, type checking, implementation details
|
||||
|
||||
---
|
||||
|
||||
### 🔍 [08: Troubleshooting](08-troubleshooting.md)
|
||||
|
||||
Common issues and solutions:
|
||||
- **Installation Issues** - Dependency and build problems
|
||||
- **Performance Problems** - Memory and speed optimization
|
||||
- **Algorithm Selection** - Choosing the right approach
|
||||
- **Platform-Specific Issues** - WASM, Node.js, and Rust quirks
|
||||
- **Debugging Guide** - Tools and techniques
|
||||
- **FAQ** - Frequently asked questions
|
||||
|
||||
**Perfect for**: Problem solving, debugging, performance issues
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
### Core Documentation
|
||||
- **[RuVector MinCut README](../../README.md)** - Project overview and features
|
||||
- **[Benchmark Report](../BENCHMARK_REPORT.md)** - Performance analysis and comparisons
|
||||
- **[API Documentation](https://docs.rs/ruvector-mincut)** - Full Rust API docs
|
||||
|
||||
### RuVector Platform
|
||||
- **[RuVector Main Repository](https://github.com/ruvnet/ruvector)** - Complete platform
|
||||
- **[RuVector Database](../../../ruvector-db/README.md)** - Vector database integration
|
||||
- **[Platform Website](https://ruv.io)** - Cloud services and support
|
||||
|
||||
### Community
|
||||
- **[GitHub Issues](https://github.com/ruvnet/ruvector/issues)** - Bug reports and feature requests
|
||||
- **[Discussions](https://github.com/ruvnet/ruvector/discussions)** - Community Q&A
|
||||
- **[Contributing Guide](../../CONTRIBUTING.md)** - How to contribute
|
||||
|
||||
---
|
||||
|
||||
## Navigation Tips
|
||||
|
||||
### 🎯 Quick Navigation
|
||||
|
||||
- Use the **table of contents** at the top of each guide page
|
||||
- Follow **"Next Steps"** links at the bottom of each section
|
||||
- Check **cross-references** for related topics
|
||||
- Use the **search** function in your viewer
|
||||
|
||||
### 📱 Mobile-Friendly
|
||||
|
||||
All documentation is optimized for reading on:
|
||||
- Desktop browsers
|
||||
- Mobile devices
|
||||
- Tablets
|
||||
- Documentation viewers (VS Code, GitHub, etc.)
|
||||
|
||||
### 🔖 Bookmarking
|
||||
|
||||
Recommended bookmarks for frequent reference:
|
||||
- [Getting Started](01-getting-started.md) - Quick setup
|
||||
- [API Reference](07-api-reference.md) - API lookup
|
||||
- [Troubleshooting](08-troubleshooting.md) - Problem solving
|
||||
- [Benchmark Report](../BENCHMARK_REPORT.md) - Performance data
|
||||
|
||||
---
|
||||
|
||||
## Document Status
|
||||
|
||||
| Section | Status | Last Updated | Completeness |
|
||||
|---------|--------|--------------|--------------|
|
||||
| Getting Started | ✅ Complete | 2025-12-22 | 100% |
|
||||
| Core Concepts | ✅ Complete | 2025-12-22 | 100% |
|
||||
| Practical Applications | ✅ Complete | 2025-12-22 | 100% |
|
||||
| Integration Guide | ✅ Complete | 2025-12-22 | 100% |
|
||||
| Advanced Examples | ✅ Complete | 2025-12-22 | 100% |
|
||||
| RuVector Ecosystem | ✅ Complete | 2025-12-22 | 100% |
|
||||
| API Reference | ✅ Complete | 2025-12-22 | 100% |
|
||||
| Troubleshooting | ✅ Complete | 2025-12-22 | 100% |
|
||||
|
||||
---
|
||||
|
||||
## About This Guide
|
||||
|
||||
### Version Information
|
||||
- **Guide Version**: 1.0.0
|
||||
- **RuVector MinCut Version**: 0.1.0
|
||||
- **Last Updated**: December 22, 2025
|
||||
- **Maintained By**: RuVector Team
|
||||
|
||||
### Contributing
|
||||
|
||||
Found an issue or want to improve this guide?
|
||||
- **Report Issues**: [GitHub Issues](https://github.com/ruvnet/ruvector/issues)
|
||||
- **Suggest Edits**: [Pull Requests](https://github.com/ruvnet/ruvector/pulls)
|
||||
- **Ask Questions**: [Discussions](https://github.com/ruvnet/ruvector/discussions)
|
||||
|
||||
### License
|
||||
|
||||
This documentation is licensed under the MIT License, same as RuVector MinCut.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**Ready to get started?**
|
||||
|
||||
[Begin with Getting Started →](01-getting-started.md)
|
||||
|
||||
---
|
||||
|
||||
Built with ❤️ by the [RuVector Team](https://ruv.io)
|
||||
|
||||
[](https://ruv.io)
|
||||
[](https://github.com/ruvnet/ruvector)
|
||||
[](https://docs.rs/ruvector-mincut)
|
||||
|
||||
</div>
|
||||
1199
vendor/ruvector/crates/ruvector-mincut/docs/security/BMSSP-SECURITY-REVIEW.md
vendored
Normal file
1199
vendor/ruvector/crates/ruvector-mincut/docs/security/BMSSP-SECURITY-REVIEW.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
270
vendor/ruvector/crates/ruvector-mincut/docs/sparsification_implementation.md
vendored
Normal file
270
vendor/ruvector/crates/ruvector-mincut/docs/sparsification_implementation.md
vendored
Normal file
@@ -0,0 +1,270 @@
|
||||
# Graph Sparsification Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
Implemented complete graph sparsification module at `/home/user/ruvector/crates/ruvector-mincut/src/sparsify/mod.rs` for (1+ε)-approximate minimum cuts using O(n log n / ε²) edges.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### 1. Core Structures
|
||||
|
||||
#### SparsifyConfig
|
||||
```rust
|
||||
pub struct SparsifyConfig {
|
||||
pub epsilon: f64, // Approximation parameter (0 < ε ≤ 1)
|
||||
pub seed: Option<u64>, // Random seed for reproducibility
|
||||
pub max_edges: Option<usize>, // Maximum edges limit
|
||||
}
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Builder pattern with `with_seed()` and `with_max_edges()`
|
||||
- Validation for epsilon parameter
|
||||
- Default configuration with ε = 0.1
|
||||
|
||||
#### SparseGraph
|
||||
```rust
|
||||
pub struct SparseGraph {
|
||||
graph: DynamicGraph, // The sparsified graph
|
||||
edge_weights: HashMap<EdgeId, Weight>, // Original weights
|
||||
epsilon: f64, // Approximation parameter
|
||||
original_edges: usize, // Original edge count
|
||||
rng: StdRng, // Random number generator
|
||||
strength_calc: EdgeStrength, // Edge strength calculator
|
||||
}
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- `from_graph()`: Create sparsified version using Benczúr-Karger
|
||||
- `num_edges()`: Get edge count (should be O(n log n / ε²))
|
||||
- `sparsification_ratio()`: Ratio of sparse to original edges
|
||||
- `approximate_min_cut()`: Query approximate minimum cut
|
||||
- `insert_edge()`: Dynamic edge insertion with resampling
|
||||
- `delete_edge()`: Dynamic edge deletion
|
||||
- `epsilon()`: Get approximation parameter
|
||||
|
||||
### 2. Sparsification Algorithms
|
||||
|
||||
#### Benczúr-Karger Sparsification
|
||||
**Algorithm:**
|
||||
1. Compute edge strengths λ_e for all edges
|
||||
2. Calculate sampling probability: p_e = min(1, c·log(n) / (ε²·λ_e))
|
||||
3. Sample each edge with probability p_e
|
||||
4. Scale sampled edge weights by 1/p_e
|
||||
|
||||
**Implementation:**
|
||||
```rust
|
||||
fn benczur_karger_sparsify(
|
||||
original: &DynamicGraph,
|
||||
sparse: &DynamicGraph,
|
||||
edge_weights: &mut HashMap<EdgeId, Weight>,
|
||||
strength_calc: &mut EdgeStrength,
|
||||
epsilon: f64,
|
||||
rng: &mut StdRng,
|
||||
max_edges: Option<usize>,
|
||||
) -> Result<()>
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- Preserves (1±ε) approximation of all cuts
|
||||
- O(n log n / ε²) expected edges
|
||||
- Randomized algorithm with seed control
|
||||
|
||||
#### Edge Strength Calculation
|
||||
```rust
|
||||
pub struct EdgeStrength {
|
||||
graph: Arc<DynamicGraph>,
|
||||
strengths: HashMap<EdgeId, f64>,
|
||||
}
|
||||
```
|
||||
|
||||
**Methods:**
|
||||
- `compute(u, v)`: Compute strength of edge (u,v)
|
||||
- `compute_all()`: Compute all edge strengths
|
||||
- `invalidate(v)`: Invalidate cached strengths for vertex v
|
||||
|
||||
**Approximation Strategy:**
|
||||
- True strength: max-flow between u and v without edge (u,v)
|
||||
- Approximation: minimum of sum of incident edge weights at u and v
|
||||
- Caching for efficiency
|
||||
|
||||
#### Nagamochi-Ibaraki Sparsification
|
||||
**Deterministic sparsification** preserving k-connectivity:
|
||||
|
||||
```rust
|
||||
pub struct NagamochiIbaraki {
|
||||
graph: Arc<DynamicGraph>,
|
||||
}
|
||||
```
|
||||
|
||||
**Algorithm:**
|
||||
1. Compute minimum degree ordering of vertices
|
||||
2. Scan vertices to determine edge connectivity
|
||||
3. Keep only edges with connectivity ≥ k
|
||||
|
||||
**Implementation:**
|
||||
```rust
|
||||
pub fn sparse_k_certificate(&self, k: usize) -> Result<DynamicGraph>
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- Deterministic (no randomness)
|
||||
- O(nk) edges for k-connectivity
|
||||
- Exact preservation of minimum cuts up to value k
|
||||
|
||||
### 3. Utility Functions
|
||||
|
||||
#### Karger's Sparsification
|
||||
Convenience function combining configuration and sparsification:
|
||||
```rust
|
||||
pub fn karger_sparsify(
|
||||
graph: &DynamicGraph,
|
||||
epsilon: f64,
|
||||
seed: Option<u64>,
|
||||
) -> Result<SparseGraph>
|
||||
```
|
||||
|
||||
#### Sample Probability
|
||||
Computes edge sampling probability based on strength:
|
||||
```rust
|
||||
fn sample_probability(strength: f64, epsilon: f64, n: f64, c: f64) -> f64
|
||||
```
|
||||
|
||||
Formula: `p_e = min(1, c·log(n) / (ε²·λ_e))`
|
||||
- Constant c = 6.0 for theoretical guarantees
|
||||
- Higher strength → lower probability
|
||||
- Always capped at 1.0
|
||||
|
||||
## Testing
|
||||
|
||||
### Comprehensive Test Suite (25 tests)
|
||||
|
||||
**Configuration Tests:**
|
||||
- `test_sparsify_config_default()`: Default configuration
|
||||
- `test_sparsify_config_new()`: Custom epsilon
|
||||
- `test_sparsify_config_invalid_epsilon()`: Validation
|
||||
- `test_sparsify_config_builder()`: Builder pattern
|
||||
|
||||
**SparseGraph Tests:**
|
||||
- `test_sparse_graph_triangle()`: Small graph sparsification
|
||||
- `test_sparse_graph_sparsification_ratio()`: Ratio calculation
|
||||
- `test_sparse_graph_max_edges()`: Edge limit enforcement
|
||||
- `test_sparse_graph_empty_graph()`: Error handling
|
||||
- `test_sparse_graph_approximate_min_cut()`: Min cut approximation
|
||||
- `test_sparse_graph_insert_edge()`: Dynamic insertion
|
||||
- `test_sparse_graph_delete_edge()`: Dynamic deletion
|
||||
|
||||
**Edge Strength Tests:**
|
||||
- `test_edge_strength_compute()`: Strength calculation
|
||||
- `test_edge_strength_compute_all()`: Batch computation
|
||||
- `test_edge_strength_invalidate()`: Cache invalidation
|
||||
- `test_edge_strength_caching()`: Cache correctness
|
||||
|
||||
**Nagamochi-Ibaraki Tests:**
|
||||
- `test_nagamochi_ibaraki_min_degree_ordering()`: Ordering algorithm
|
||||
- `test_nagamochi_ibaraki_sparse_certificate()`: Certificate generation
|
||||
- `test_nagamochi_ibaraki_scan_connectivity()`: Connectivity scanning
|
||||
- `test_nagamochi_ibaraki_empty_graph()`: Error handling
|
||||
|
||||
**Integration Tests:**
|
||||
- `test_karger_sparsify()`: Convenience function
|
||||
- `test_sample_probability()`: Probability bounds
|
||||
- `test_sparsification_preserves_vertices()`: Vertex preservation
|
||||
- `test_sparsification_weighted_graph()`: Weighted edges
|
||||
- `test_deterministic_with_seed()`: Reproducibility
|
||||
- `test_sparse_graph_ratio_bounds()`: Ratio properties
|
||||
|
||||
## Example Usage
|
||||
|
||||
See `/home/user/ruvector/crates/ruvector-mincut/examples/sparsify_demo.rs` for complete demonstration.
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::graph::DynamicGraph;
|
||||
use ruvector_mincut::sparsify::{SparsifyConfig, SparseGraph};
|
||||
|
||||
// Create graph
|
||||
let graph = DynamicGraph::new();
|
||||
graph.insert_edge(1, 2, 1.0).unwrap();
|
||||
graph.insert_edge(2, 3, 1.0).unwrap();
|
||||
graph.insert_edge(3, 4, 1.0).unwrap();
|
||||
graph.insert_edge(4, 1, 1.0).unwrap();
|
||||
|
||||
// Sparsify with ε = 0.1
|
||||
let config = SparsifyConfig::new(0.1)
|
||||
.unwrap()
|
||||
.with_seed(42);
|
||||
|
||||
let sparse = SparseGraph::from_graph(&graph, config).unwrap();
|
||||
|
||||
println!("Original: {} edges", graph.num_edges());
|
||||
println!("Sparse: {} edges", sparse.num_edges());
|
||||
println!("Ratio: {:.2}%", sparse.sparsification_ratio() * 100.0);
|
||||
println!("Approx min cut: {:.2}", sparse.approximate_min_cut());
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### Benczúr-Karger Sparsification
|
||||
- **Time Complexity:** O(m + n log n / ε²) where m = original edges
|
||||
- **Space Complexity:** O(n log n / ε²)
|
||||
- **Edge Count:** O(n log n / ε²) expected
|
||||
- **Approximation:** (1±ε) for all cuts
|
||||
|
||||
### Nagamochi-Ibaraki Sparsification
|
||||
- **Time Complexity:** O(m + nk)
|
||||
- **Space Complexity:** O(nk)
|
||||
- **Edge Count:** O(nk)
|
||||
- **Approximation:** Exact for cuts ≤ k
|
||||
|
||||
### Edge Strength Calculation
|
||||
- **Time Complexity:** O(m) for all edges (with caching)
|
||||
- **Space Complexity:** O(m)
|
||||
- **Approximation:** Local connectivity-based heuristic
|
||||
|
||||
## Key Features
|
||||
|
||||
1. **Dynamic Updates:** Support for edge insertion/deletion with resampling
|
||||
2. **Reproducibility:** Seed-based random number generation
|
||||
3. **Flexibility:** Multiple sparsification algorithms
|
||||
4. **Efficiency:** Caching and lazy computation
|
||||
5. **Validation:** Comprehensive error handling
|
||||
6. **Testing:** 25+ unit tests covering all functionality
|
||||
7. **Documentation:** Extensive inline documentation and examples
|
||||
|
||||
## Theoretical Guarantees
|
||||
|
||||
### Benczúr-Karger Theorem
|
||||
For any graph G with n vertices and any ε ∈ (0,1], there exists a sparse graph H with:
|
||||
- O(n log n / ε²) edges
|
||||
- For every cut (S, V\S): (1-ε)·w_G(S) ≤ w_H(S) ≤ (1+ε)·w_G(S)
|
||||
|
||||
### Nagamochi-Ibaraki Theorem
|
||||
For any graph G with edge connectivity λ, the k-connectivity certificate has:
|
||||
- At most nk edges
|
||||
- Preserves all cuts of value ≤ k exactly
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
1. **Implementation:** `/home/user/ruvector/crates/ruvector-mincut/src/sparsify/mod.rs` (847 lines)
|
||||
2. **Example:** `/home/user/ruvector/crates/ruvector-mincut/examples/sparsify_demo.rs` (94 lines)
|
||||
3. **Documentation:** This file
|
||||
|
||||
## Build Status
|
||||
|
||||
✅ **Compilation:** Successful (no errors)
|
||||
✅ **Documentation:** Generated successfully
|
||||
✅ **Example:** Runs correctly
|
||||
✅ **Warnings:** Only minor unused import warnings (cleaned up)
|
||||
|
||||
## Next Steps
|
||||
|
||||
The sparsification module is complete and ready for integration with:
|
||||
- Dynamic minimum cut algorithms
|
||||
- Real-time graph monitoring
|
||||
- Approximate query processing
|
||||
- Large-scale graph analytics
|
||||
|
||||
## References
|
||||
|
||||
- Benczúr, A. A., & Karger, D. R. (1996). Approximating s-t minimum cuts in Õ(n²) time
|
||||
- Nagamochi, H., & Ibaraki, T. (1992). Computing edge-connectivity in multigraphs and capacitated graphs
|
||||
201
vendor/ruvector/crates/ruvector-mincut/docs/witness-quick-reference.md
vendored
Normal file
201
vendor/ruvector/crates/ruvector-mincut/docs/witness-quick-reference.md
vendored
Normal file
@@ -0,0 +1,201 @@
|
||||
# Witness Trees - Quick Reference
|
||||
|
||||
## API Overview
|
||||
|
||||
### Creating a Witness Tree
|
||||
|
||||
```rust
|
||||
use std::sync::Arc;
|
||||
use parking_lot::RwLock;
|
||||
use ruvector_mincut::{DynamicGraph, WitnessTree};
|
||||
|
||||
let graph = Arc::new(RwLock::new(DynamicGraph::new()));
|
||||
let witness = WitnessTree::build(graph)?;
|
||||
```
|
||||
|
||||
### Core Operations
|
||||
|
||||
| Operation | Method | Complexity | Description |
|
||||
|-----------|--------|------------|-------------|
|
||||
| Get min cut | `min_cut_value()` | O(1) | Returns current minimum cut value |
|
||||
| Get cut edges | `min_cut_edges()` | O(1) | Returns edges in minimum cut |
|
||||
| Insert edge | `insert_edge(u, v, w)` | O(log n) | Add edge to graph |
|
||||
| Delete edge | `delete_edge(u, v)` | O(m) worst | Remove edge from graph |
|
||||
| Is tree edge | `is_tree_edge(u, v)` | O(1) | Check if edge is in spanning tree |
|
||||
| Find witness | `find_witness(u, v)` | O(1) | Get witness for tree edge |
|
||||
|
||||
### Lazy Updates (Batched)
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::LazyWitnessTree;
|
||||
|
||||
let mut lazy = LazyWitnessTree::with_threshold(graph, 10)?;
|
||||
|
||||
// Batch 10 updates
|
||||
for i in 1..=10 {
|
||||
lazy.insert_edge(i, i+1, 1.0)?;
|
||||
}
|
||||
|
||||
// Force flush and get result
|
||||
let min_cut = lazy.min_cut_value();
|
||||
```
|
||||
|
||||
## Data Structures
|
||||
|
||||
### EdgeWitness
|
||||
|
||||
```rust
|
||||
pub struct EdgeWitness {
|
||||
pub tree_edge: (VertexId, VertexId), // Canonical form (min, max)
|
||||
pub cut_value: Weight, // Value of this cut
|
||||
pub cut_side: HashSet<VertexId>, // Vertices on one side
|
||||
}
|
||||
```
|
||||
|
||||
### WitnessTree
|
||||
|
||||
- **lct**: Link-Cut Tree for O(log n) connectivity
|
||||
- **witnesses**: HashMap of tree edge witnesses
|
||||
- **tree_edges**: Spanning forest edges
|
||||
- **non_tree_edges**: Cycle-forming edges
|
||||
- **min_cut**: Cached minimum cut value
|
||||
- **min_cut_edges**: Edges in the minimum cut
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Building from Existing Graph
|
||||
|
||||
```rust
|
||||
// Graph already has edges
|
||||
let graph = Arc::new(RwLock::new(DynamicGraph::new()));
|
||||
graph.write().insert_edge(1, 2, 1.0)?;
|
||||
graph.write().insert_edge(2, 3, 1.0)?;
|
||||
|
||||
// Build witness tree
|
||||
let witness = WitnessTree::build(graph.clone())?;
|
||||
```
|
||||
|
||||
### Dynamic Construction
|
||||
|
||||
```rust
|
||||
// Start empty
|
||||
let graph = Arc::new(RwLock::new(DynamicGraph::new()));
|
||||
let mut witness = WitnessTree::build(graph.clone())?;
|
||||
|
||||
// Add edges dynamically
|
||||
graph.write().insert_edge(1, 2, 1.0)?;
|
||||
witness.insert_edge(1, 2, 1.0)?;
|
||||
|
||||
graph.write().insert_edge(2, 3, 1.0)?;
|
||||
witness.insert_edge(2, 3, 1.0)?;
|
||||
```
|
||||
|
||||
### Checking Tree Structure
|
||||
|
||||
```rust
|
||||
// Find which edges are in the spanning tree
|
||||
for (u, v) in all_edges {
|
||||
if witness.is_tree_edge(u, v) {
|
||||
if let Some(w) = witness.find_witness(u, v) {
|
||||
println!("Edge ({}, {}) has witness cut {}", u, v, w.cut_value);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### Disconnected Graph
|
||||
```rust
|
||||
// Returns 0.0 (no cut exists)
|
||||
let min_cut = witness.min_cut_value();
|
||||
assert_eq!(min_cut, 0.0);
|
||||
```
|
||||
|
||||
### Single Vertex
|
||||
```rust
|
||||
// Returns infinity
|
||||
let min_cut = witness.min_cut_value();
|
||||
assert!(min_cut.is_infinite());
|
||||
```
|
||||
|
||||
### Empty Graph
|
||||
```rust
|
||||
// Returns infinity
|
||||
let min_cut = witness.min_cut_value();
|
||||
assert!(min_cut.is_infinite());
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Use Lazy Updates**: For sequences of operations, use `LazyWitnessTree`
|
||||
2. **Batch Threshold**: Tune threshold based on update pattern (default: 10)
|
||||
3. **Avoid Repeated Queries**: Cache `min_cut_value()` result if querying multiple times
|
||||
4. **Tree Edge Queries**: Check `is_tree_edge()` before `find_witness()`
|
||||
|
||||
## Implementation Statistics
|
||||
|
||||
- **Lines of Code**: 910
|
||||
- **Functions**: 46
|
||||
- **Tests**: 20 (all passing ✓)
|
||||
- **Test Coverage**: Comprehensive
|
||||
- Basic functionality (4 tests)
|
||||
- Dynamic updates (5 tests)
|
||||
- Correctness (5 tests)
|
||||
- Advanced features (6 tests)
|
||||
|
||||
## Example: Complete Workflow
|
||||
|
||||
```rust
|
||||
use std::sync::Arc;
|
||||
use parking_lot::RwLock;
|
||||
use ruvector_mincut::{DynamicGraph, WitnessTree};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
// Create graph
|
||||
let graph = Arc::new(RwLock::new(DynamicGraph::new()));
|
||||
|
||||
// Add initial edges
|
||||
graph.write().insert_edge(1, 2, 1.0)?;
|
||||
graph.write().insert_edge(2, 3, 1.0)?;
|
||||
graph.write().insert_edge(3, 1, 1.0)?;
|
||||
|
||||
// Build witness tree
|
||||
let mut witness = WitnessTree::build(graph.clone())?;
|
||||
|
||||
// Query
|
||||
println!("Initial min cut: {}", witness.min_cut_value());
|
||||
println!("Cut edges: {:?}", witness.min_cut_edges());
|
||||
|
||||
// Dynamic update
|
||||
graph.write().insert_edge(1, 4, 2.0)?;
|
||||
let new_cut = witness.insert_edge(1, 4, 2.0)?;
|
||||
println!("After insert: {}", new_cut);
|
||||
|
||||
// Delete edge
|
||||
graph.write().delete_edge(1, 2)?;
|
||||
let updated_cut = witness.delete_edge(1, 2)?;
|
||||
println!("After delete: {}", updated_cut);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```rust
|
||||
// Insert returns Result
|
||||
match witness.insert_edge(u, v, weight) {
|
||||
Ok(new_cut) => println!("Success: {}", new_cut),
|
||||
Err(e) => eprintln!("Error: {}", e),
|
||||
}
|
||||
|
||||
// Delete returns Result
|
||||
match witness.delete_edge(u, v) {
|
||||
Ok(new_cut) => println!("Success: {}", new_cut),
|
||||
Err(MinCutError::EdgeNotFound(u, v)) => {
|
||||
eprintln!("Edge ({}, {}) not found", u, v);
|
||||
}
|
||||
Err(e) => eprintln!("Error: {}", e),
|
||||
}
|
||||
```
|
||||
304
vendor/ruvector/crates/ruvector-mincut/docs/witness-trees.md
vendored
Normal file
304
vendor/ruvector/crates/ruvector-mincut/docs/witness-trees.md
vendored
Normal file
@@ -0,0 +1,304 @@
|
||||
# Witness Trees Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the implementation of Witness Trees for dynamic minimum cut maintenance, following the Jin-Sun-Thorup algorithm from SODA 2024: "Fully Dynamic Exact Minimum Cut in Subpolynomial Time".
|
||||
|
||||
## What are Witness Trees?
|
||||
|
||||
Witness trees maintain a spanning forest of a graph where each tree edge is "witnessed" by a cut that certifies its inclusion in the tree. This data structure enables efficient dynamic maintenance of minimum cuts.
|
||||
|
||||
### Key Properties
|
||||
|
||||
1. **Witness Invariant**: Each tree edge (u,v) has a witness cut C such that removing (u,v) from the tree reveals C
|
||||
2. **Minimum Cut Certificate**: The minimum among all witness cuts equals the graph's minimum cut
|
||||
3. **Lazy Updates**: Updates are performed lazily to achieve better amortized complexity
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
```
|
||||
WitnessTree
|
||||
├── LinkCutTree # Dynamic connectivity queries
|
||||
├── Witnesses # HashMap of edge witnesses
|
||||
├── Tree Edges # Spanning forest edges
|
||||
├── Non-Tree Edges # Cycle-forming edges
|
||||
└── Min Cut Info # Cached minimum cut value and edges
|
||||
```
|
||||
|
||||
### Key Data Structures
|
||||
|
||||
```rust
|
||||
// Witness for a tree edge
|
||||
pub struct EdgeWitness {
|
||||
pub tree_edge: (VertexId, VertexId),
|
||||
pub cut_value: Weight,
|
||||
pub cut_side: HashSet<VertexId>, // One side of the cut
|
||||
}
|
||||
|
||||
// Main witness tree structure
|
||||
pub struct WitnessTree {
|
||||
lct: LinkCutTree, // O(log n) connectivity
|
||||
witnesses: HashMap<(VertexId, VertexId), EdgeWitness>,
|
||||
min_cut: Weight,
|
||||
min_cut_edges: Vec<Edge>,
|
||||
graph: Arc<RwLock<DynamicGraph>>,
|
||||
dirty: bool,
|
||||
tree_edges: HashSet<(VertexId, VertexId)>,
|
||||
non_tree_edges: HashSet<(VertexId, VertexId)>,
|
||||
}
|
||||
```
|
||||
|
||||
## Algorithm Details
|
||||
|
||||
### Build Phase
|
||||
|
||||
```rust
|
||||
fn build_spanning_tree() -> Result<()>
|
||||
```
|
||||
|
||||
1. **Spanning Tree Construction** (BFS):
|
||||
- O(n + m) time
|
||||
- Creates spanning forest for disconnected graphs
|
||||
- Identifies tree vs non-tree edges
|
||||
|
||||
2. **Witness Computation**:
|
||||
- For each tree edge (u,v):
|
||||
- Find components after removing (u,v)
|
||||
- Compute cut value between components
|
||||
- Store witness
|
||||
|
||||
**Complexity**: O(n·m) for initial build
|
||||
|
||||
### Insert Edge
|
||||
|
||||
```rust
|
||||
pub fn insert_edge(u, v, weight) -> Result<Weight>
|
||||
```
|
||||
|
||||
**Case 1: Bridge Edge** (u and v in different components)
|
||||
- Add to spanning tree
|
||||
- Link in Link-Cut Tree
|
||||
- Compute witness for new edge
|
||||
- Update min cut if needed
|
||||
|
||||
**Case 2: Cycle Edge** (u and v already connected)
|
||||
- Add to non-tree edges
|
||||
- Mark dirty for recomputation
|
||||
- May improve minimum cut
|
||||
|
||||
**Complexity**: Amortized O(log n) with lazy updates
|
||||
|
||||
### Delete Edge
|
||||
|
||||
```rust
|
||||
pub fn delete_edge(u, v) -> Result<Weight>
|
||||
```
|
||||
|
||||
**Case 1: Tree Edge**
|
||||
- Remove from spanning tree
|
||||
- Cut in Link-Cut Tree
|
||||
- Find replacement edge in non-tree edges
|
||||
- If found: add to tree, compute witness
|
||||
- Update min cut
|
||||
|
||||
**Case 2: Non-Tree Edge**
|
||||
- Remove from non-tree edges
|
||||
- Mark dirty for recomputation
|
||||
|
||||
**Complexity**: O(m) worst case (finding replacement), O(log n) amortized
|
||||
|
||||
### Finding Minimum Cut
|
||||
|
||||
```rust
|
||||
fn recompute_min_cut()
|
||||
```
|
||||
|
||||
1. Examine all tree edge witnesses
|
||||
2. Find witness with minimum cut value
|
||||
3. Collect edges in that cut
|
||||
4. Cache result
|
||||
|
||||
**Complexity**: O(number of tree edges) = O(n)
|
||||
|
||||
## Optimizations
|
||||
|
||||
### 1. Lazy Witness Tree
|
||||
|
||||
```rust
|
||||
pub struct LazyWitnessTree {
|
||||
inner: WitnessTree,
|
||||
pending_updates: Vec<(VertexId, VertexId, bool)>,
|
||||
batch_threshold: usize,
|
||||
}
|
||||
```
|
||||
|
||||
- Batches updates together
|
||||
- Flushes when threshold reached
|
||||
- Better amortized complexity for sequences
|
||||
|
||||
### 2. Link-Cut Tree Integration
|
||||
|
||||
- O(log n) connectivity queries
|
||||
- O(log n) link/cut operations
|
||||
- Path compression for efficiency
|
||||
|
||||
### 3. Canonical Edge Keys
|
||||
|
||||
```rust
|
||||
fn canonical_key(u, v) -> (VertexId, VertexId) {
|
||||
if u <= v { (u, v) } else { (v, u) }
|
||||
}
|
||||
```
|
||||
|
||||
- Consistent edge representation
|
||||
- Efficient HashMap lookups
|
||||
- Avoids duplicate edges
|
||||
|
||||
## Complexity Analysis
|
||||
|
||||
| Operation | Time Complexity | Space Complexity |
|
||||
|-----------|----------------|------------------|
|
||||
| Build | O(n·m) | O(n + m) |
|
||||
| Insert Edge | O(log n) amortized | O(1) |
|
||||
| Delete Edge | O(m) worst, O(log n) amortized | O(1) |
|
||||
| Min Cut Query | O(1) | - |
|
||||
| Find Witness | O(1) | - |
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Thread Safety
|
||||
|
||||
The implementation uses `Arc<RwLock<DynamicGraph>>` for thread-safe graph access:
|
||||
- Multiple concurrent reads allowed
|
||||
- Exclusive write access when modifying
|
||||
|
||||
### Edge Cases Handled
|
||||
|
||||
1. **Empty Graph**: Returns ∞ for min cut
|
||||
2. **Disconnected Graph**: Returns 0 (no cut exists)
|
||||
3. **Single Vertex**: Returns ∞
|
||||
4. **Dynamic Vertices**: Automatically adds new vertices to LCT
|
||||
|
||||
### Limitations
|
||||
|
||||
1. **Spanning Tree Dependency**: Only considers cuts corresponding to tree edges
|
||||
2. **Approximation**: May not find optimal cut if it doesn't correspond to tree structure
|
||||
3. **Replacement Search**: Finding replacement edges is O(m) in worst case
|
||||
|
||||
## Testing
|
||||
|
||||
The implementation includes 20 comprehensive tests:
|
||||
|
||||
### Basic Functionality
|
||||
- `test_build_empty` - Empty graph handling
|
||||
- `test_build_single_vertex` - Single vertex
|
||||
- `test_build_triangle` - Simple connected graph
|
||||
- `test_build_bridge` - Bridge detection
|
||||
|
||||
### Dynamic Updates
|
||||
- `test_insert_bridge_edge` - Adding bridge edges
|
||||
- `test_insert_cycle_edge` - Adding cycle edges
|
||||
- `test_delete_tree_edge` - Removing tree edges
|
||||
- `test_delete_non_tree_edge` - Removing non-tree edges
|
||||
- `test_dynamic_sequence` - Sequence of operations
|
||||
|
||||
### Correctness
|
||||
- `test_is_tree_edge` - Tree edge identification
|
||||
- `test_find_witness` - Witness retrieval
|
||||
- `test_tree_edge_cut` - Cut value computation
|
||||
- `test_weighted_edges` - Weighted graph support
|
||||
- `test_canonical_key` - Edge key normalization
|
||||
|
||||
### Advanced Features
|
||||
- `test_lazy_witness_tree` - Lazy updates
|
||||
- `test_lazy_witness_batch_threshold` - Batching
|
||||
- `test_disconnected_graph` - Multiple components
|
||||
- `test_large_graph` - Scalability (100 vertices)
|
||||
- `test_complete_graph` - Dense graphs
|
||||
|
||||
### All Tests Pass ✓
|
||||
|
||||
```bash
|
||||
test result: ok. 20 passed; 0 failed; 0 ignored
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```rust
|
||||
use std::sync::Arc;
|
||||
use parking_lot::RwLock;
|
||||
use ruvector_mincut::{DynamicGraph, WitnessTree};
|
||||
|
||||
// Create graph
|
||||
let graph = Arc::new(RwLock::new(DynamicGraph::new()));
|
||||
graph.write().insert_edge(1, 2, 1.0).unwrap();
|
||||
graph.write().insert_edge(2, 3, 1.0).unwrap();
|
||||
graph.write().insert_edge(3, 1, 1.0).unwrap();
|
||||
|
||||
// Build witness tree
|
||||
let mut witness = WitnessTree::build(graph.clone()).unwrap();
|
||||
|
||||
// Query minimum cut
|
||||
println!("Min cut: {}", witness.min_cut_value());
|
||||
println!("Cut edges: {:?}", witness.min_cut_edges());
|
||||
```
|
||||
|
||||
### Dynamic Updates
|
||||
|
||||
```rust
|
||||
// Insert edge
|
||||
graph.write().insert_edge(1, 4, 2.0).unwrap();
|
||||
let new_cut = witness.insert_edge(1, 4, 2.0).unwrap();
|
||||
println!("New min cut: {}", new_cut);
|
||||
|
||||
// Delete edge
|
||||
graph.write().delete_edge(1, 2).unwrap();
|
||||
let updated_cut = witness.delete_edge(1, 2).unwrap();
|
||||
```
|
||||
|
||||
### Lazy Updates
|
||||
|
||||
```rust
|
||||
use ruvector_mincut::LazyWitnessTree;
|
||||
|
||||
let mut lazy = LazyWitnessTree::with_threshold(graph, 10).unwrap();
|
||||
|
||||
// Batch updates
|
||||
for i in 1..10 {
|
||||
graph.write().insert_edge(i, i+1, 1.0).unwrap();
|
||||
lazy.insert_edge(i, i+1, 1.0).unwrap();
|
||||
}
|
||||
|
||||
// Force flush and get result
|
||||
let min_cut = lazy.min_cut_value();
|
||||
```
|
||||
|
||||
## Future Improvements
|
||||
|
||||
1. **Parallel Witness Computation**: Compute witnesses in parallel for large graphs
|
||||
2. **Incremental Updates**: More efficient incremental witness updates
|
||||
3. **Approximate Witnesses**: Trade accuracy for speed in large graphs
|
||||
4. **Persistent Data Structures**: Better support for versioning and rollback
|
||||
|
||||
## References
|
||||
|
||||
- Jin, C., & Sun, R., & Thorup, M. (2024). "Fully Dynamic Exact Minimum Cut in Subpolynomial Time". SODA 2024.
|
||||
- Sleator, D. D., & Tarjan, R. E. (1983). "A data structure for dynamic trees". Journal of Computer and System Sciences.
|
||||
|
||||
## File Location
|
||||
|
||||
`/home/user/ruvector/crates/ruvector-mincut/src/witness/mod.rs`
|
||||
|
||||
## Integration
|
||||
|
||||
The witness tree module is fully integrated into the ruvector-mincut crate:
|
||||
|
||||
```rust
|
||||
pub use witness::{WitnessTree, LazyWitnessTree, EdgeWitness};
|
||||
```
|
||||
|
||||
Available in the prelude for convenient access.
|
||||
Reference in New Issue
Block a user