Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/examples/mincut/morphogenetic/README.md

@@ -0,0 +1,240 @@
+# 🧬 Morphogenetic Network Growth
+
+A biological-inspired network growth simulation demonstrating how complex structures emerge from simple local rules.
+
+## 📖 What is Morphogenesis?
+
+**Morphogenesis** is the biological process that causes an organism to develop its shape. In embryonic development, a single fertilized egg grows into a complex organism through:
+
+1. **Cell Division** - cells multiply
+2. **Cell Differentiation** - cells specialize
+3. **Pattern Formation** - structures emerge
+4. **Growth Signals** - chemical gradients coordinate development
+
+This example applies these biological principles to network growth!
+
+## 🌱 Concept Overview
+
+### Traditional Networks
+- Designed top-down by architects
+- Global structure explicitly specified
+- Centralized control
+
+### Morphogenetic Networks
+- **Grow bottom-up from local rules**
+- **Global structure emerges naturally**
+- **Distributed autonomous control**
+
+Think of it like the difference between:
+- 🏗️ Building a house (traditional): architect designs every room
+- 🌳 Growing a tree (morphogenetic): genetic code + local rules → complex structure
+
+## 🧬 The Biological Analogy
+
+| Biology | Network |
+|---------|---------|
+| **Embryo** | Seed network (4 nodes) |
+| **Morphogens** | Growth signals (0.0-1.0) |
+| **Gene Expression** | Growth rules (if-then) |
+| **Cell Division** | Node spawning |
+| **Differentiation** | Branching/specialization |
+| **Chemical Gradients** | Signal diffusion |
+| **Maturity** | Stable structure |
+
+## 🎯 Growth Rules
+
+The network grows based on **local rules** at each node (like genes):
+
+### Rule 1: Low Connectivity → Growth
+```
+IF node_degree < 3 AND growth_signal > 0.5
+THEN spawn_new_node()
+```
+**Biological**: Underdeveloped areas need more cells
+
+### Rule 2: High Degree → Branching
+```
+IF node_degree > 5 AND growth_signal > 0.6
+THEN create_branch()
+```
+**Biological**: Overcrowded cells differentiate into specialized branches
+
+### Rule 3: Weak Cuts → Reinforcement
+```
+IF local_mincut < 2 AND growth_signal > 0.4
+THEN reinforce_connectivity()
+```
+**Biological**: Weak structures need strengthening
+
+### Rule 4: Signal Diffusion
+```
+EACH cycle:
+  node keeps 60% of signal
+  shares 40% with neighbors
+```
+**Biological**: Morphogen gradients coordinate development
+
+### Rule 5: Aging
+```
+EACH cycle:
+  signals decay by 10%
+  node_age increases
+```
+**Biological**: Growth slows as organism matures
+
+## 🚀 Running the Example
+
+```bash
+cargo run --example morphogenetic
+
+# Or from the examples directory:
+cd examples/mincut/morphogenetic
+cargo run
+```
+
+## 📊 What You'll See
+
+### Growth Cycle Output
+```
+🌱 Growth Cycle 3 🌱
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🌿 Node 2 spawned child 6 (low connectivity: degree=2)
+  💪 Node 4 reinforced (mincut=1.5), added node 7
+  🌳 Node 1 branched to 8 (high degree: 6)
+
+  📊 Network Statistics:
+     Nodes: 9 (+2 spawned)
+     Edges: 14
+     Branches: 1 new
+     Reinforcements: 1
+     Avg Growth Signal: 0.723
+     Density: 0.389
+```
+
+### Development Stages
+
+1. **Seed (Cycle 0)**: 4 nodes, circular structure
+2. **Early Growth (Cycles 1-5)**: Rapid expansion, signal diffusion
+3. **Differentiation (Cycles 6-10)**: Branching, specialization
+4. **Maturation (Cycles 11-15)**: Stabilization, signal decay
+5. **Adult Form**: Final stable structure (~20-30 nodes)
+
+## 💡 Key Insights
+
+### Emergent Complexity
+- **No central planner** - each node follows local rules
+- **Complex structure emerges** from simple rules
+- **Self-organizing** - no explicit global design
+
+### Local → Global
+- Local rules at nodes (IF degree > 5 THEN branch)
+- Global patterns emerge (hub-and-spoke, hierarchies)
+- Like how DNA → organism without a blueprint of the final form
+
+### Distributed Intelligence
+- Each node acts independently
+- Coordination through signal diffusion
+- Collective behavior without central control
+
+## 🔬 Real-World Applications
+
+### Network Design
+- **Self-healing networks**: grow around failures
+- **Adaptive infrastructure**: grows where needed
+- **Organic scaling**: natural capacity expansion
+
+### Distributed Systems
+- **Peer-to-peer networks**: organic topology
+- **Sensor networks**: self-organizing coverage
+- **Social networks**: natural community formation
+
+### Optimization
+- **Resource allocation**: grow where demand is high
+- **Load balancing**: branch when overloaded
+- **Resilience**: reinforce weak connections
+
+## 🧪 Experiment Ideas
+
+### 1. Change Growth Rules
+Modify the rules in `main.rs`:
+```rust
+// More aggressive branching
+if signal > 0.4 && degree > 3 {  // was: 0.6 and 5
+    branch_node(node);
+}
+```
+
+### 2. Different Seed Structures
+```rust
+// Star seed instead of circular
+let network = MorphogeneticNetwork::new_star(5, 15);
+```
+
+### 3. Multiple Signal Types
+Add "specialization signals" for different node types:
+```rust
+growth_signals: HashMap<usize, Vec<f64>>  // multiple signal channels
+```
+
+### 4. Environmental Pressures
+Add external forces that influence growth:
+```rust
+fn apply_gravity(&mut self) {
+    // Nodes "fall" creating vertical structures
+}
+```
+
+## 📚 Further Reading
+
+### Biological Morphogenesis
+- [Turing's Morphogenesis Paper](https://royalsocietypublishing.org/doi/10.1098/rstb.1952.0012) (1952)
+- [D'Arcy Thompson - On Growth and Form](https://en.wikipedia.org/wiki/On_Growth_and_Form)
+
+### Network Science
+- [Emergence in Complex Networks](https://www.nature.com/subjects/complex-networks)
+- [Self-Organizing Systems](https://en.wikipedia.org/wiki/Self-organization)
+
+### Algorithms
+- [Genetic Algorithms](https://en.wikipedia.org/wiki/Genetic_algorithm)
+- [Cellular Automata](https://en.wikipedia.org/wiki/Cellular_automaton)
+- [L-Systems](https://en.wikipedia.org/wiki/L-system) (plant growth modeling)
+
+## 🎯 Learning Objectives
+
+After running this example, you should understand:
+
+1. ✅ How **local rules create global patterns**
+2. ✅ The power of **distributed decision-making**
+3. ✅ How **biological principles apply to networks**
+4. ✅ Why **emergent behavior** matters
+5. ✅ How **simple algorithms** can create **complex structures**
+
+## 🌟 The Big Idea
+
+> **Complex systems don't need complex controllers.**
+>
+> Just like a tree doesn't have a "brain" that decides where each branch grows, networks can self-organize through simple local rules. The magic is in the emergence - the whole becomes greater than the sum of its parts.
+
+This is the essence of morphogenesis: **local simplicity, global complexity**.
+
+---
+
+## 🔗 Related Examples
+
+- **Temporal Networks**: Networks that evolve over time
+- **Cascade Failures**: How network structure affects resilience
+- **Community Detection**: Finding natural groupings
+
+## 🤝 Contributing
+
+Ideas for extending this example:
+- [ ] 3D visualization of growth
+- [ ] Multiple species competition
+- [ ] Energy/resource constraints
+- [ ] Sexual reproduction (graph merging)
+- [ ] Predator-prey dynamics
+- [ ] Environmental adaptation
+
+---
+
+**Happy Growing! 🌱→🌳**