dearsky/wifi-densepose
1
0
Fork 0
Code Issues 20 Pull Requests 5 Actions Packages Projects Releases 1 Wiki Activity

Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

Browse Source
This commit is contained in:
ruv
2026-02-28 14:39:40 -05:00
parent 7885bf6278 d803bfe2b1
commit cd5943df23
7854 changed files with 3522914 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

395
vendor/ruvector/examples/mincut/README.md vendored Normal file
View File

@@ -0,0 +1,395 @@
# Networks That Think For Themselves
[![Crates.io](https://img.shields.io/crates/v/ruvector-mincut.svg)](https://crates.io/crates/ruvector-mincut)
[![Documentation](https://docs.rs/ruvector-mincut/badge.svg)](https://docs.rs/ruvector-mincut)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-ruvnet%2Fruvector-blue?logo=github)](https://github.com/ruvnet/ruvector)
[![ruv.io](https://img.shields.io/badge/ruv.io-AI%20Infrastructure-orange)](https://ruv.io)
What if your infrastructure could heal itself before you noticed it was broken? What if a drone swarm could reorganize mid-flight without any central command? What if an AI system knew exactly where its own blind spots were?
These aren't science fiction — they're **self-organizing systems**, and they all share a secret: they understand their own weakest points.
---
## The Core Insight
Every network has a **minimum cut** — the smallest set of connections that, if broken, would split the system apart. This single number reveals everything about a network's vulnerability:
```
Strong Network (min-cut = 6) Fragile Network (min-cut = 1)
●───●───● ●───●
│ × │ × │ vs │
●───●───● ●────●────●
│ × │ × │ │
●───●───● ●───●
"Many paths between any two points" "One bridge holds everything together"
```
**The breakthrough**: When a system can observe its own minimum cut in real-time, it gains the ability to:
- **Know** where it's vulnerable (self-awareness)
- **Fix** weak points before they fail (self-healing)
- **Learn** which structures work best (self-optimization)
These six examples show how to build systems with these capabilities.
---
## What You'll Build
| Example | One-Line Description | Real Application |
|---------|---------------------|------------------|
| **Temporal Attractors** | Networks that evolve toward stability | Drone swarms finding optimal formations |
| **Strange Loop** | Systems that observe and modify themselves | Self-healing infrastructure |
| **Causal Discovery** | Tracing cause-and-effect in failures | Debugging distributed systems |
| **Time Crystal** | Self-sustaining periodic patterns | Automated shift scheduling |
| **Morphogenetic** | Networks that grow like organisms | Auto-scaling cloud services |
| **Neural Optimizer** | ML that learns optimal structures | Network architecture search |
---
## Quick Start
```bash
# Run from workspace root using ruvector-mincut
cargo run -p ruvector-mincut --release --example temporal_attractors
cargo run -p ruvector-mincut --release --example strange_loop
cargo run -p ruvector-mincut --release --example causal_discovery
cargo run -p ruvector-mincut --release --example time_crystal
cargo run -p ruvector-mincut --release --example morphogenetic
cargo run -p ruvector-mincut --release --example neural_optimizer
# Run benchmarks
cargo run -p ruvector-mincut --release --example benchmarks
```
---
## The Six Examples
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ SELF-ORGANIZING NETWORK PATTERNS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Temporal │ │ Strange │ │ Causal │ │
│ │ Attractors │ │ Loop │ │ Discovery │ │
│ │ │ │ │ │ │ │
│ │ Networks that │ │ Self-aware │ │ Find cause & │ │
│ │ evolve toward │ │ swarms that │ │ effect in │ │
│ │ stable states │ │ reorganize │ │ dynamic graphs │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Time │ │ Morpho- │ │ Neural │ │
│ │ Crystal │ │ genetic │ │ Optimizer │ │
│ │ │ │ │ │ │ │
│ │ Periodic │ │ Bio-inspired │ │ Learn optimal │ │
│ │ coordination │ │ network │ │ graph configs │ │
│ │ patterns │ │ growth │ │ over time │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
### 1. Temporal Attractors
Drop a marble into a bowl. No matter where you release it, it always ends up at the bottom. The bottom is an **attractor** — a stable state the system naturally evolves toward.
Networks have attractors too. Some configurations are "sticky" — once a network gets close, it stays there. This example shows how to design networks that *want* to be resilient.
**What it does**: Networks that naturally evolve toward stable states without central control — chaos becomes order, weakness becomes strength.
```
Time →
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
│Chaos│ ──► │Weak │ ──► │Strong│ ──► │Stable│
│mc=1 │ │mc=2 │ │mc=4 │ │mc=6 │
└─────┘ └─────┘ └─────┘ └─────┘
ATTRACTOR
```
**The magic moment**: You start with a random, fragile network. Apply simple local rules. Watch as it *autonomously* reorganizes into a robust structure — no orchestrator required.
**Real-world applications:**
- **Drone swarms** that find optimal formations even when GPS fails
- **Microservice meshes** that self-balance without load balancers
- **Social platforms** where toxic clusters naturally isolate themselves
- **Power grids** that stabilize after disturbances
**Key patterns:**
| Attractor Type | Behavior | Use Case |
|----------------|----------|----------|
| Optimal | Network strengthens over time | Reliability engineering |
| Fragmented | Network splits into clusters | Community detection |
| Oscillating | Periodic connectivity changes | Load balancing |
**Run:** `cargo run -p ruvector-mincut --release --example temporal_attractors`
---
### 2. Strange Loop Swarms
You look in a mirror. You see yourself looking. You adjust your hair *because* you saw it was messy. The act of observing changed what you observed.
This is a **strange loop** — and it's the secret to building systems that improve themselves.
**What it does**: A swarm of agents that continuously monitors its own connectivity, identifies weak points, and strengthens them — all without external commands.
```
┌──────────────────────────────────────────┐
│ STRANGE LOOP │
│ │
│ Observe ──► Model ──► Decide ──► Act │
│ ▲ │ │
│ └──────────────────────────────┘ │
│ │
│ "I see I'm weak here, so I strengthen" │
└──────────────────────────────────────────┘
```
**The magic moment**: The swarm computes its own minimum cut. It discovers node 7 is a single point of failure. It adds a redundant connection. The next time it checks, the vulnerability is gone — *because it fixed itself*.
**Real-world applications:**
- **Self-healing Kubernetes clusters** that add replicas when connectivity drops
- **AI agents** that recognize uncertainty and request human oversight
- **Mesh networks** that reroute around failures before users notice
- **Autonomous drone swarms** that maintain formation despite losing members
**Why "strange"?** The loop creates a paradox: the system that does the observing is the same system being observed. This self-reference is what enables genuine autonomy — the system doesn't need external monitoring because it *is* its own monitor.
**Run:** `cargo run -p ruvector-mincut --release --example strange_loop`
---
### 3. Causal Discovery
3 AM. Pager goes off. The website is down. You check the frontend — it's timing out. You check the API — it's overwhelmed. You check the database — connection pool exhausted. You check the cache — it crashed 10 minutes ago.
**The cache crash caused everything.** But you spent 45 minutes finding that out.
This example finds root causes automatically by watching *when* things break and in *what order*.
**What it does**: Monitors network changes over time and automatically discovers cause-and-effect chains using timing analysis.
```
Event A Event B Event C
(edge cut) (mincut drops) (partition)
│ │ │
├────200ms────────┤ │
│ ├────500ms───────┤
│ │
└──────────700ms───────────────────┘
Discovered: A causes B causes C
```
**The magic moment**: Your monitoring shows 47 network events in the last minute. The algorithm traces backward through time and reports: *"Event 12 (cache disconnect) triggered cascade affecting 31 downstream services."* Root cause found in milliseconds.
**Real-world applications:**
- **Incident response**: Skip the detective work, go straight to the fix
- **Security forensics**: Trace exactly how an attacker moved through your network
- **Financial systems**: Understand how market shocks propagate
- **Epidemiology**: Model how diseases spread through contact networks
**The science**: This uses Granger causality — if knowing A happened helps predict B will happen, then A likely causes B. Combined with minimum cut tracking, you see exactly which connections carried the failure.
**Run:** `cargo run -p ruvector-mincut --release --example causal_discovery`
---
### 4. Time Crystal Coordination
In physics, a time crystal is matter that moves in a repeating pattern *forever* — without using energy. It shouldn't be possible, but it exists.
This example creates the software equivalent: network topologies that cycle through configurations indefinitely, with no external scheduler, no cron jobs, no orchestrator. The pattern sustains itself.
**What it does**: Creates self-perpetuating periodic patterns where the network autonomously transitions between different configurations on a fixed rhythm.
```
Phase 1 Phase 2 Phase 3 Phase 1...
Ring Star Mesh Ring
●─● ● ●─●─● ●─●
│ │ /│\ │╲│╱│ │ │
●─● ● ● ● ●─●─● ●─●
mc=2 mc=1 mc=6 mc=2
└─────────────── REPEATS FOREVER ───────────────┘
```
**The magic moment**: You configure three topology phases. You start the system. You walk away. Come back in a week — it's still cycling perfectly. No scheduler crashed. No missed transitions. The rhythm is *encoded in the network itself*.
**Real-world applications:**
- **Blue-green deployments** that alternate automatically
- **Database maintenance windows** that cycle through replica sets
- **Security rotations** where credentials/keys cycle on schedule
- **Distributed consensus** where leader election follows predictable patterns
**Why this works**: Each phase's minimum cut naturally creates instability that triggers the transition to the next phase. The cycle is self-reinforcing — phase 1 *wants* to become phase 2.
**Run:** `cargo run -p ruvector-mincut --release --example time_crystal`
---
### 5. Morphogenetic Networks
A fertilized egg has no blueprint of a human body. Yet it grows into one — heart, lungs, brain — all from simple local rules: *"If my neighbors are doing X, I should do Y."*
This is **morphogenesis**: complex structure emerging from simple rules. And it works for networks too.
**What it does**: Networks that grow organically from a seed, developing structure based on local conditions — no central planner, no predefined topology.
```
Seed Sprout Branch Mature
● → ●─● → ●─●─● → ●─●─●
│ │ │ │ │
● ● ●─●─●
│ │
●───●
```
**The magic moment**: You plant a single node. You define three rules. You wait. The network grows, branches, strengthens weak points, and eventually stabilizes into a mature structure — one you never explicitly designed.
**Real-world applications:**
- **Kubernetes clusters** that grow pods based on load, not fixed replica counts
- **Neural architecture search**: Let the network *evolve* its own structure
- **Urban planning simulations**: Model how cities naturally develop
- **Startup scaling**: Infrastructure that grows exactly as fast as you need
**How it works:**
| Signal | Rule | Biological Analogy |
|--------|------|-------------------|
| Growth | "If min-cut is low, add connections" | Cells multiply in nutrient-rich areas |
| Branch | "If too connected, split" | Limbs branch to distribute load |
| Mature | "If stable for N cycles, stop" | Organism reaches adult size |
**Why minimum cut matters**: The min-cut acts like a growth hormone. Low min-cut = vulnerability = signal to grow. High min-cut = stability = signal to stop. The network literally *senses* its own health.
**Run:** `cargo run -p ruvector-mincut --release --example morphogenetic`
---
### 6. Neural Graph Optimizer
Every time you run a minimum cut algorithm, you're throwing away valuable information. You computed something hard — then forgot it. Next time, you start from scratch.
What if your system *remembered*? What if it learned: *"Graphs that look like this usually have min-cut around 5"*? After enough experience, it could predict answers instantly — and use the exact algorithm only to verify.
**What it does**: Trains a neural network to predict minimum cuts, then uses those predictions to make smarter modifications — learning what works over time.
```
┌─────────────────────────────────────────────┐
│ NEURAL OPTIMIZATION LOOP │
│ │
│ ┌─────────┐ ┌─────────┐ ┌────────┐ │
│ │ Observe │───►│ Predict │───►│ Act │ │
│ │ Graph │ │ MinCut │ │ Modify │ │
│ └─────────┘ └─────────┘ └────────┘ │
│ ▲ │ │
│ └─────────── Learn ───────────┘ │
└─────────────────────────────────────────────┘
```
**The magic moment**: After 1,000 training iterations, your neural network predicts min-cuts with 94% accuracy in microseconds. You're now making decisions 100x faster than pure algorithmic approaches — and the predictions keep improving.
**Real-world applications:**
- **CDN optimization**: Learn which edge server topologies minimize latency
- **Game AI**: NPCs that learn optimal patrol routes through level graphs
- **Chip design**: Predict which wire layouts minimize critical paths
- **Drug discovery**: Learn which molecular bond patterns indicate stability
**The hybrid advantage:**
| Approach | Speed | Accuracy | Improves Over Time |
|----------|-------|----------|-------------------|
| Pure algorithm | Medium | 100% | No |
| Pure neural | Fast | ~80% | Yes |
| **Hybrid** | **Fast** | **95%+** | **Yes** |
**Why this matters**: The algorithm provides ground truth for training. The neural network provides speed for inference. Together, you get a system that starts smart and gets smarter.
**Run:** `cargo run -p ruvector-mincut --release --example neural_optimizer`
---
## Performance
Traditional minimum cut algorithms take **seconds to minutes** on large graphs. That's fine for offline analysis — but useless for self-organizing systems that need to react in real-time.
These examples run on [RuVector MinCut](https://crates.io/crates/ruvector-mincut), which implements the December 2025 breakthrough achieving **subpolynomial update times**. Translation: microseconds instead of seconds.
**Why this changes everything:**
| Old Reality | New Reality |
|-------------|-------------|
| Compute min-cut once, hope network doesn't change | Recompute on every change, react instantly |
| Self-healing requires external monitoring | Systems monitor themselves continuously |
| Learning requires batch processing | Learn from every event in real-time |
| Scale limited by algorithm speed | Scale limited only by memory |
### Benchmark Results
| Example | Typical Scale | Update Speed | Memory |
|---------|--------------|--------------|--------|
| Temporal Attractors | 1,000 nodes | ~50 μs | ~1 MB |
| Strange Loop | 500 nodes | ~100 μs | ~500 KB |
| Causal Discovery | 1,000 events | ~10 μs/event | ~100 KB |
| Time Crystal | 100 nodes | ~20 μs/phase | ~200 KB |
| Morphogenetic | 10→100 nodes | ~200 μs/cycle | ~500 KB |
| Neural Optimizer | 500 nodes | ~1 ms/step | ~2 MB |
**50 microseconds** = 20,000 updates per second. That's fast enough for a drone swarm to recalculate optimal formation every time a single drone moves.
All examples scale to 10,000+ nodes. Run benchmarks:
```bash
cargo run -p ruvector-mincut --release --example benchmarks
```
---
## When to Use Each Pattern
| Problem | Best Example | Why |
|---------|--------------|-----|
| "My system needs to find a stable configuration" | Temporal Attractors | Natural convergence to optimal states |
| "My system should fix itself when broken" | Strange Loop | Self-observation enables self-repair |
| "I need to debug cascading failures" | Causal Discovery | Traces cause-effect chains |
| "I need periodic rotation between modes" | Time Crystal | Self-sustaining cycles |
| "My system should grow organically" | Morphogenetic | Bio-inspired scaling |
| "I want my system to learn and improve" | Neural Optimizer | ML + graph algorithms |
---
## Dependencies
```toml
[dependencies]
ruvector-mincut = { version = "0.1.26", features = ["monitoring", "approximate"] }
```
---
## Further Reading
| Topic | Resource | Why It Matters |
|-------|----------|----------------|
| Attractors | [Dynamical Systems Theory](https://en.wikipedia.org/wiki/Attractor) | Mathematical foundation for stability |
| Strange Loops | [Hofstadter, "Gödel, Escher, Bach"](https://en.wikipedia.org/wiki/Strange_loop) | Self-reference and consciousness |
| Causality | [Granger Causality](https://en.wikipedia.org/wiki/Granger_causality) | Statistical cause-effect detection |
| Time Crystals | [Wilczek, 2012](https://en.wikipedia.org/wiki/Time_crystal) | Physics of periodic systems |
| Morphogenesis | [Turing Patterns](https://en.wikipedia.org/wiki/Turing_pattern) | How biology creates structure |
| Neural Optimization | [Neural Combinatorial Optimization](https://arxiv.org/abs/1611.09940) | ML for graph problems |
---
<div align="center">
**Built with [RuVector MinCut](https://crates.io/crates/ruvector-mincut)**
[ruv.io](https://ruv.io) | [GitHub](https://github.com/ruvnet/ruvector) | [Docs](https://docs.rs/ruvector-mincut)
</div>