Squashed 'vendor/ruvector/' content from commit b64c2172
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
This commit is contained in:
ruv
334
examples/mincut/temporal_attractors/README.md
Normal file
334
examples/mincut/temporal_attractors/README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Temporal Attractor Networks with MinCut Analysis
|
||||
|
||||
This example demonstrates how networks evolve toward stable "attractor states" and how minimum cut analysis helps detect convergence to these attractors.
|
||||
|
||||
## What are Temporal Attractors?
|
||||
|
||||
In **dynamical systems theory**, an **attractor** is a state toward which a system naturally evolves over time, regardless of initial conditions (within a basin).
|
||||
|
||||
### Real-World Analogies
|
||||
|
||||
```
|
||||
🏔️ Gravitational Attractor
|
||||
╱╲ ball
|
||||
╱ ╲ ↓
|
||||
╱____╲ valley (attractor)
|
||||
|
||||
🌊 Hydraulic Attractor
|
||||
╱╲ ╱╲
|
||||
╱ ╲_╱ ╲ ← water flows to lowest point
|
||||
|
||||
🕸️ Network Attractor
|
||||
Sparse → Dense
|
||||
◯ ◯ ◯═◯
|
||||
╲╱ → ║╳║ (maximum connectivity)
|
||||
◯ ◯═◯
|
||||
```
|
||||
|
||||
### Three Types of Network Attractors
|
||||
|
||||
#### 1️⃣ Optimal Attractor (Maximum Connectivity)
|
||||
|
||||
**What it is**: Network evolves toward maximum connectivity and robustness.
|
||||
|
||||
```
|
||||
Initial State (Ring): Final State (Dense):
|
||||
◯─◯─◯ ◯═◯═◯
|
||||
│ │ ║╳║╳║
|
||||
◯─◯─◯ ◯═◯═◯
|
||||
MinCut: 1 MinCut: 6+
|
||||
```
|
||||
|
||||
**MinCut Evolution**:
|
||||
```
|
||||
Step: 0 10 20 30 40 50
|
||||
│ │ │ │ │ │
|
||||
MinCut 1 ───2────4────5────6────6 (stable)
|
||||
↑ ↑
|
||||
Adding edges Converged!
|
||||
```
|
||||
|
||||
**Why it matters for swarms**:
|
||||
- ✅ Fault-tolerant communication
|
||||
- ✅ Maximum information flow
|
||||
- ✅ Robust against node failures
|
||||
- ✅ Optimal for multi-agent coordination
|
||||
|
||||
#### 2️⃣ Fragmented Attractor (Network Collapse)
|
||||
|
||||
**What it is**: Network fragments into disconnected clusters.
|
||||
|
||||
```
|
||||
Initial State (Connected): Final State (Fragmented):
|
||||
◯─◯─◯ ◯─◯ ◯
|
||||
│ │ ╲│
|
||||
◯─◯─◯ ◯ ◯─◯
|
||||
MinCut: 1 MinCut: 0
|
||||
```
|
||||
|
||||
**MinCut Evolution**:
|
||||
```
|
||||
Step: 0 10 20 30 40 50
|
||||
│ │ │ │ │ │
|
||||
MinCut 1 ───1────0────0────0────0 (stable)
|
||||
↓ ↑
|
||||
Removing edges Disconnected!
|
||||
```
|
||||
|
||||
**Why it matters for swarms**:
|
||||
- ❌ Communication breakdown
|
||||
- ❌ Isolated agents
|
||||
- ❌ Coordination failure
|
||||
- ❌ Poor swarm performance
|
||||
|
||||
#### 3️⃣ Oscillating Attractor (Limit Cycle)
|
||||
|
||||
**What it is**: Network oscillates between states periodically.
|
||||
|
||||
```
|
||||
State A: State B: State A:
|
||||
◯═◯ ◯─◯ ◯═◯
|
||||
║ ║ → │ │ → ║ ║ ...
|
||||
◯═◯ ◯─◯ ◯═◯
|
||||
```
|
||||
|
||||
**MinCut Evolution**:
|
||||
```
|
||||
Step: 0 10 20 30 40 50
|
||||
│ │ │ │ │ │
|
||||
MinCut 1 ───3────1────3────1────3 (periodic)
|
||||
↗ ↘ ↗ ↘ ↗ ↘ ↗ ↘
|
||||
Oscillating pattern!
|
||||
```
|
||||
|
||||
**Why it matters for swarms**:
|
||||
- ⚠️ Unstable equilibrium
|
||||
- ⚠️ May indicate resonance
|
||||
- ⚠️ Requires damping
|
||||
- ⚠️ Unpredictable behavior
|
||||
|
||||
## How MinCut Detects Convergence
|
||||
|
||||
The **minimum cut value** serves as a "thermometer" for network health:
|
||||
|
||||
### Convergence Patterns
|
||||
|
||||
```
|
||||
📈 INCREASING MinCut → Strengthening
|
||||
0─1─2─3─4─5─6─6─6 ✅ Converging to optimal
|
||||
└─┴─ Stable (attractor reached)
|
||||
|
||||
📉 DECREASING MinCut → Fragmenting
|
||||
6─5─4─3─2─1─0─0─0 ❌ Network collapsing
|
||||
└─┴─ Stable (disconnected)
|
||||
|
||||
🔄 OSCILLATING MinCut → Limit Cycle
|
||||
1─3─1─3─1─3─1─3─1 ⚠️ Periodic pattern
|
||||
└─┴─┴─┴─┴─┴─┴─── Oscillating attractor
|
||||
```
|
||||
|
||||
### Mathematical Interpretation
|
||||
|
||||
**Variance Analysis**:
|
||||
```
|
||||
Variance = Σ(MinCut[i] - Mean)² / N
|
||||
|
||||
Low Variance (< 0.5): STABLE → Attractor reached ✓
|
||||
High Variance (> 5): OSCILLATING → Limit cycle ⚠️
|
||||
Medium Variance: TRANSITIONING → Still evolving
|
||||
```
|
||||
|
||||
## Why This Matters for Swarms
|
||||
|
||||
### Multi-Agent Systems Naturally Form Attractors
|
||||
|
||||
```
|
||||
Agent Swarm Evolution:
|
||||
|
||||
t=0: Random deployment t=20: Self-organizing t=50: Converged
|
||||
🤖 🤖 🤖─🤖 🤖═🤖
|
||||
🤖 🤖 🤖 ╱│ │╲ ║╳║╳║
|
||||
🤖 🤖 🤖─🤖─🤖 🤖═🤖═🤖
|
||||
|
||||
MinCut: 0 MinCut: 2 MinCut: 6 (stable)
|
||||
(disconnected) (organizing) (optimal attractor)
|
||||
```
|
||||
|
||||
### Real-World Applications
|
||||
|
||||
1. **Drone Swarms**: Need optimal attractor for coordination
|
||||
- MinCut monitors communication strength
|
||||
- Detects when swarm has stabilized
|
||||
- Warns if swarm is fragmenting
|
||||
|
||||
2. **Distributed Computing**: Optimal attractor = efficient topology
|
||||
- MinCut shows network resilience
|
||||
- Identifies bottlenecks early
|
||||
- Validates load balancing
|
||||
|
||||
3. **Social Networks**: Understanding community formation
|
||||
- MinCut reveals cluster strength
|
||||
- Detects community splits
|
||||
- Predicts group stability
|
||||
|
||||
## Running the Example
|
||||
|
||||
```bash
|
||||
# Build and run
|
||||
cd /home/user/ruvector/examples/mincut/temporal_attractors
|
||||
cargo run --release
|
||||
|
||||
# Expected output: 3 scenarios showing different attractor types
|
||||
```
|
||||
|
||||
### Understanding the Output
|
||||
|
||||
```
|
||||
Step | MinCut | Edges | Avg Conn | Time(μs) | Status
|
||||
------|--------|-------|----------|----------|------------------
|
||||
0 | 1 | 10 | 1.00 | 45 | evolving...
|
||||
5 | 2 | 15 | 1.50 | 52 | evolving...
|
||||
10 | 4 | 23 | 2.30 | 68 | evolving...
|
||||
15 | 6 | 31 | 3.10 | 89 | evolving...
|
||||
20 | 6 | 34 | 3.40 | 95 | ✓ CONVERGED
|
||||
```
|
||||
|
||||
**Key Metrics**:
|
||||
- **MinCut**: Network's bottleneck capacity
|
||||
- **Edges**: Total connections
|
||||
- **Avg Conn**: Average edges per node
|
||||
- **Time**: Performance per evolution step
|
||||
- **Status**: Convergence detection
|
||||
|
||||
## Code Structure
|
||||
|
||||
### Main Components
|
||||
|
||||
```rust
|
||||
// 1. Network snapshot (state at each time step)
|
||||
NetworkSnapshot {
|
||||
step: usize,
|
||||
mincut: u64,
|
||||
edge_count: usize,
|
||||
avg_connectivity: f64,
|
||||
}
|
||||
|
||||
// 2. Attractor network (evolving system)
|
||||
AttractorNetwork {
|
||||
graph: Graph,
|
||||
attractor_type: AttractorType,
|
||||
history: Vec<NetworkSnapshot>,
|
||||
}
|
||||
|
||||
// 3. Evolution methods (dynamics)
|
||||
evolve_toward_optimal() // Add shortcuts, strengthen edges
|
||||
evolve_toward_fragmented() // Remove edges, weaken connections
|
||||
evolve_toward_oscillating() // Alternate add/remove
|
||||
```
|
||||
|
||||
### Key Methods
|
||||
|
||||
```rust
|
||||
// Evolve one time step
|
||||
network.evolve_step() -> NetworkSnapshot
|
||||
|
||||
// Check if converged to attractor
|
||||
network.has_converged(window: usize) -> bool
|
||||
|
||||
// Get evolution history
|
||||
network.history() -> &[NetworkSnapshot]
|
||||
|
||||
// Calculate current mincut
|
||||
calculate_mincut() -> u64
|
||||
```
|
||||
|
||||
## Key Insights
|
||||
|
||||
### 1. MinCut as Health Monitor
|
||||
|
||||
```
|
||||
High MinCut (6+): Healthy, robust network ✅
|
||||
Medium MinCut (2-5): Moderate connectivity ⚠️
|
||||
Low MinCut (1): Fragile, single bottleneck ⚠️
|
||||
Zero MinCut (0): Disconnected, failed ❌
|
||||
```
|
||||
|
||||
### 2. Convergence Detection
|
||||
|
||||
```rust
|
||||
// Stable variance → Attractor reached
|
||||
variance < 0.5 ⟹ Equilibrium
|
||||
variance > 5.0 ⟹ Oscillating
|
||||
```
|
||||
|
||||
### 3. Evolution Speed
|
||||
|
||||
```
|
||||
Optimal Attractor: Fast convergence (10-20 steps)
|
||||
Fragmented Attractor: Medium speed (15-30 steps)
|
||||
Oscillating Attractor: Never converges (limit cycle)
|
||||
```
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Basin of Attraction
|
||||
|
||||
```
|
||||
Optimal Basin Fragmented Basin
|
||||
╱ ╲ ╱ ╲
|
||||
│ ┌─────────┐ │ │ ┌─────┐ │
|
||||
│ │ Optimal │ │ │ │ Frag│ │
|
||||
│ │Attractor│ │ │ │ment │ │
|
||||
│ └─────────┘ │ │ └─────┘ │
|
||||
╲ ╱ ╲ ╱
|
||||
Any initial state Any initial state
|
||||
in this region → in this region →
|
||||
converges here converges here
|
||||
```
|
||||
|
||||
### Bifurcation Points
|
||||
|
||||
Critical thresholds where attractor type changes:
|
||||
```
|
||||
Parameter (e.g., edge addition rate)
|
||||
│
|
||||
│ ┌───────────── Optimal
|
||||
│ ╱
|
||||
├───────────────── Bifurcation point
|
||||
│ ╲
|
||||
│ └───────────── Fragmented
|
||||
└───────────────────────────→
|
||||
```
|
||||
|
||||
### Lyapunov Stability
|
||||
|
||||
MinCut variance measures stability:
|
||||
```
|
||||
dMinCut/dt < 0 → Stable attractor
|
||||
dMinCut/dt > 0 → Unstable, moving away
|
||||
dMinCut/dt ≈ 0 → Near equilibrium
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- **Dynamical Systems Theory**: Strogatz, "Nonlinear Dynamics and Chaos"
|
||||
- **Network Science**: Barabási, "Network Science"
|
||||
- **Swarm Intelligence**: Bonabeau et al., "Swarm Intelligence"
|
||||
- **MinCut Algorithms**: Stoer-Wagner (1997), Karger (2000)
|
||||
|
||||
## Performance Notes
|
||||
|
||||
- **Time Complexity**: O(V³) per step (dominated by mincut calculation)
|
||||
- **Space Complexity**: O(V + E + H) where H is history length
|
||||
- **Typical Runtime**: ~50-100μs per step for 10-node networks
|
||||
|
||||
## Educational Value
|
||||
|
||||
This example teaches:
|
||||
1. ✅ What temporal attractors are and why they matter
|
||||
2. ✅ How networks naturally evolve toward stable states
|
||||
3. ✅ Using MinCut as a convergence detector
|
||||
4. ✅ Interpreting attractor basins and stability
|
||||
5. ✅ Applying these concepts to multi-agent swarms
|
||||
|
||||
Perfect for understanding how swarms self-organize and how to monitor their health!
|
||||
Reference in New Issue
Block a user