Skip to content

Commit 8378d8b

Browse files
fermgafermga
authored
Merge pull request #2799 from fermga/copilot/add-integration-tests-um
[WIP] Add complete usage example and integration tests for UM
2 parents 81e9579 + 37aa20f commit 8378d8b

File tree

3 files changed

+738
-0
lines changed

3 files changed

+738
-0
lines changed

‎GLYPH_SEQUENCES_GUIDE.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,82 @@ run_sequence(G, community, [Coupling(), Resonance()])
258258
# Result: Coherence propagates through coupled network
259259
```
260260

261+
**Extended UM Examples** (from `examples/coupling_network_formation.py`):
262+
263+
#### Network Synchronization with UM
264+
```python
265+
from tnfr.sdk import TNFRNetwork, NetworkConfig
266+
267+
# Create network with varied phases
268+
net = TNFRNetwork("network_sync_demo", NetworkConfig(random_seed=42))
269+
net.add_nodes(8)
270+
271+
# Set distinct phase groups
272+
for i, node in enumerate(net.graph.nodes()):
273+
net.graph.nodes[node]['theta'] = (i % 4) * math.pi / 2
274+
275+
# Apply network_sync sequence (includes UM)
276+
# Sequence: AL → EN → IL → UM → RA → NAV
277+
net.apply_sequence("network_sync", repeat=2)
278+
279+
results = net.measure()
280+
# Result: Phase spread reduced, coherence increased through UM
281+
print(f"Coherence: {results.coherence:.3f}")
282+
```
283+
284+
#### Building Networks from Isolated Nodes
285+
```python
286+
# Start with isolated nodes
287+
net = TNFRNetwork("formation", NetworkConfig(random_seed=42))
288+
net.add_nodes(15)
289+
290+
# Add connections
291+
net.connect_nodes(0.25, "random")
292+
293+
# Apply formation sequence with UM
294+
net.apply_sequence("network_sync", repeat=3)
295+
net.apply_sequence("consolidation", repeat=2)
296+
297+
results = net.measure()
298+
# Result: Coherent network formed from isolated nodes
299+
print(f"Network Coherence: {results.coherence:.3f}")
300+
```
301+
302+
#### Bridging Incompatible Phase Groups
303+
```python
304+
net = TNFRNetwork("phase_merging", NetworkConfig(random_seed=42))
305+
net.add_nodes(10)
306+
307+
# Create opposing phase groups (maximally incompatible)
308+
for i, node in enumerate(net.graph.nodes()):
309+
if i < 5:
310+
net.graph.nodes[node]['theta'] = 0.0 # Group 1
311+
else:
312+
net.graph.nodes[node]['theta'] = math.pi # Group 2
313+
314+
net.connect_nodes(0.3, "random")
315+
316+
# Apply repeated synchronization to bridge gap
317+
for _ in range(3):
318+
net.apply_sequence("network_sync")
319+
320+
results = net.measure()
321+
# Result: UM successfully merged incompatible phase groups
322+
print(f"Final coherence: {results.coherence:.3f}")
323+
```
324+
325+
**Key UM Principles**:
326+
1. **Phase Synchronization**: UM synchronizes θᵢ ≈ θⱼ (primary mechanism)
327+
2. **EPI Preservation**: Each node maintains its structural identity
328+
3. **Network Foundation**: UM creates substrate for RA and THOL
329+
4. **Bidirectional**: Enables mutual influence and shared coherence
330+
331+
**Typical UM Sequences**:
332+
- **AL → UM**: Emission + coupling (paired activation)
333+
- **UM → RA**: Coupling + propagation (network coherence)
334+
- **UM → IL**: Coupling + stabilization (consolidated links)
335+
- **Network_sync**: AL → EN → IL → UM → RA → NAV (complete cycle)
336+
261337
---
262338

263339
## Intermediate Sequences

‎examples/coupling_network_formation.py‎

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
"""Network Formation via Coupling (UM) - Canonical Usage Examples.
2+
3+
Demonstrates canonical UM (Coupling) operator usage to build coherent networks
4+
through phase synchronization and structural link formation.
5+
6+
This example showcases:
7+
1. network_sync sequence: Uses UM for phase synchronization
8+
2. UM → RA effects: Coupling followed by resonance propagation
9+
3. Complete network formation cycles
10+
4. Phase convergence through repeated coupling
11+
12+
UM (Coupling) synchronizes phases between nodes (θᵢ ≈ θⱼ) to enable
13+
resonant interaction while preserving each node's structural identity (EPI).
14+
This is the foundation for all network-level coherence in TNFR.
15+
"""
16+
17+
import warnings
18+
warnings.filterwarnings("ignore")
19+
20+
from tnfr.sdk import TNFRNetwork, NetworkConfig
21+
import math
22+
23+
print("\n" + "=" * 70)
24+
print("COUPLING (UM) - Network Formation Examples")
25+
print("=" * 70)
26+
print("\nStructural Function: Phase synchronization (θᵢ ≈ θⱼ)")
27+
print("Primary Effect: Creates coherent network links")
28+
print("Invariant: Preserves EPI identity of each node")
29+
print()
30+
31+
32+
def example_1_network_sync():
33+
"""Example 1: Network synchronization with UM."""
34+
print("\n" + "-" * 70)
35+
print("Example 1: Network Synchronization (network_sync sequence)")
36+
print("-" * 70)
37+
print("\nCanonical Sequence: AL → EN → IL → UM → RA → NAV")
38+
print("Purpose: Full network activation and synchronization cycle")
39+
print()
40+
41+
# Create network with varied initial phases
42+
net = TNFRNetwork("network_sync_demo", NetworkConfig(random_seed=42))
43+
net.add_nodes(8)
44+
45+
# Initialize with varied phases to show synchronization
46+
for i, node in enumerate(net.graph.nodes()):
47+
net.graph.nodes[node]['theta'] = (i % 4) * math.pi / 2 # Four phase groups
48+
49+
print("Initial state:")
50+
print(f" Nodes: {net.graph.number_of_nodes()}")
51+
phases_before = [net.graph.nodes[n]['theta'] for n in net.graph.nodes()]
52+
print(f" Phase spread: {max(phases_before) - min(phases_before):.3f} rad")
53+
print(f" Phase groups: 4 distinct phases (0, π/2, π, 3π/2)")
54+
55+
results_before = net.measure()
56+
print(f" Coherence C(t): {results_before.coherence:.3f}")
57+
58+
# Apply network_sync sequence (includes UM)
59+
print("\nApplying 'network_sync' sequence (contains UM):")
60+
print(" AL → EN → IL → UM → RA → NAV")
61+
net.apply_sequence("network_sync", repeat=2)
62+
63+
# Measure results
64+
results_after = net.measure()
65+
phases_after = [net.graph.nodes[n]['theta'] for n in net.graph.nodes()]
66+
67+
print("\nResults:")
68+
print(f" Coherence C(t): {results_after.coherence:.3f}")
69+
print(f" Phase spread: {max(phases_after) - min(phases_after):.3f} rad")
70+
coherence_gain = results_after.coherence - results_before.coherence
71+
phase_reduction = max(phases_before) - min(phases_before) - (max(phases_after) - min(phases_after))
72+
print(f" Coherence gain: {coherence_gain:+.3f}")
73+
print(f" Phase spread reduction: {phase_reduction:.3f} rad")
74+
print("\n✓ UM synchronized phases, enabling network coherence")
75+
76+
return net
77+
78+
79+
def example_2_coupling_in_connected_network():
80+
"""Example 2: Coupling effects in pre-connected network."""
81+
print("\n" + "-" * 70)
82+
print("Example 2: Coupling in Pre-Connected Network")
83+
print("-" * 70)
84+
print("\nDemonstrates: UM's effect on an existing network topology")
85+
print()
86+
87+
# Create connected network
88+
net = TNFRNetwork("connected_coupling", NetworkConfig(random_seed=42))
89+
net.add_nodes(10).connect_nodes(0.3, "random")
90+
91+
# Initialize with three phase clusters
92+
for i, node in enumerate(net.graph.nodes()):
93+
net.graph.nodes[node]['theta'] = (i % 3) * (2 * math.pi / 3)
94+
95+
print("Initial state:")
96+
print(f" Topology: Random (10 nodes, 30% connectivity)")
97+
print(f" Edges: {net.graph.number_of_edges()}")
98+
print(f" Phase clusters: 3 groups (0, 2π/3, 4π/3)")
99+
100+
results_before = net.measure()
101+
print(f" Coherence C(t): {results_before.coherence:.3f}")
102+
103+
# Apply network_sync to engage coupling
104+
print("\nApplying network_sync with UM:")
105+
net.apply_sequence("network_sync", repeat=3)
106+
107+
results_after = net.measure()
108+
phases_after = [net.graph.nodes[n]['theta'] for n in net.graph.nodes()]
109+
110+
print("\nResults:")
111+
print(f" Coherence C(t): {results_after.coherence:.3f}")
112+
print(f" Phase convergence: {max(phases_after) - min(phases_after):.3f} rad")
113+
print(f" Coherence gain: {results_after.coherence - results_before.coherence:+.3f}")
114+
print("\n✓ UM bridged phase clusters through network topology")
115+
116+
return net
117+
118+
119+
def example_3_ring_topology_coupling():
120+
"""Example 3: Coupling in ring topology (high structural coherence)."""
121+
print("\n" + "-" * 70)
122+
print("Example 3: Ring Topology Coupling")
123+
print("-" * 70)
124+
print("\nDemonstrates: UM in highly structured topology")
125+
print()
126+
127+
# Create ring network
128+
net = TNFRNetwork("ring_coupling", NetworkConfig(random_seed=42))
129+
net.add_nodes(12).connect_nodes(0.5, "ring")
130+
131+
# Initialize with linear phase progression
132+
for i, node in enumerate(net.graph.nodes()):
133+
net.graph.nodes[node]['theta'] = i * math.pi / 6 # Gradual phase shift
134+
135+
print("Initial state:")
136+
print(f" Topology: Ring (12 nodes)")
137+
print(f" Edges: {net.graph.number_of_edges()}")
138+
print(f" Phase pattern: Linear progression (0 → 11π/6)")
139+
140+
results_before = net.measure()
141+
print(f" Coherence C(t): {results_before.coherence:.3f}")
142+
143+
# Apply stabilization (includes coupling-like effects)
144+
print("\nApplying 'stabilization' sequence:")
145+
net.apply_sequence("stabilization", repeat=2)
146+
147+
results_after = net.measure()
148+
149+
print("\nResults:")
150+
print(f" Coherence C(t): {results_after.coherence:.3f}")
151+
print(f" Stability increase: {results_after.coherence - results_before.coherence:+.3f}")
152+
avg_si = sum(results_after.sense_indices.values()) / len(results_after.sense_indices)
153+
print(f" Avg Sense Index: {avg_si:.3f}")
154+
print("\n✓ Ring topology enabled efficient phase propagation")
155+
156+
return net
157+
158+
159+
def example_4_building_from_isolated_nodes():
160+
"""Example 4: Building coherent network from isolated nodes."""
161+
print("\n" + "-" * 70)
162+
print("Example 4: Network Formation from Isolated Nodes")
163+
print("-" * 70)
164+
print("\nDemonstrates: Creating coherent structure from scratch")
165+
print()
166+
167+
# Create isolated nodes
168+
net = TNFRNetwork("formation", NetworkConfig(random_seed=42))
169+
net.add_nodes(15)
170+
171+
# Highly varied initial state
172+
for i, node in enumerate(net.graph.nodes()):
173+
net.graph.nodes[node]['theta'] = (i % 5) * (2 * math.pi / 5)
174+
175+
print("Initial state (isolated nodes):")
176+
print(f" Nodes: {net.graph.number_of_nodes()}")
177+
print(f" Edges: {net.graph.number_of_edges()}")
178+
results_init = net.measure()
179+
print(f" Coherence C(t): {results_init.coherence:.3f}")
180+
181+
# Add connections
182+
print("\nPhase 1: Add random connections")
183+
net.connect_nodes(0.25, "random")
184+
print(f" Edges created: {net.graph.number_of_edges()}")
185+
186+
# Apply formation sequence
187+
print("\nPhase 2: Apply network_sync sequence (with UM)")
188+
net.apply_sequence("network_sync", repeat=3)
189+
results_mid = net.measure()
190+
print(f" Coherence after sync: {results_mid.coherence:.3f}")
191+
192+
# Stabilize
193+
print("\nPhase 3: Consolidate structure")
194+
net.apply_sequence("consolidation", repeat=2)
195+
results_final = net.measure()
196+
197+
print("\nFinal state (formed network):")
198+
print(f" Coherence C(t): {results_final.coherence:.3f}")
199+
print(f" Total gain: {results_final.coherence - results_init.coherence:+.3f}")
200+
avg_si = sum(results_final.sense_indices.values()) / len(results_final.sense_indices)
201+
print(f" Avg Sense Index: {avg_si:.3f}")
202+
print("\n✓ UM enabled network-level coherence formation")
203+
204+
return net
205+
206+
207+
def example_5_phase_group_merging():
208+
"""Example 5: Merging distinct phase groups through coupling."""
209+
print("\n" + "-" * 70)
210+
print("Example 5: Merging Phase Groups")
211+
print("-" * 70)
212+
print("\nDemonstrates: UM bridges incompatible phase groups")
213+
print()
214+
215+
# Create two distinct phase groups
216+
net = TNFRNetwork("phase_merging", NetworkConfig(random_seed=42))
217+
net.add_nodes(10)
218+
219+
# Two opposing phase groups
220+
for i, node in enumerate(net.graph.nodes()):
221+
if i < 5:
222+
net.graph.nodes[node]['theta'] = 0.0 # Group 1
223+
else:
224+
net.graph.nodes[node]['theta'] = math.pi # Group 2 (opposite)
225+
226+
print("Initial state:")
227+
print(f" Group 1 (nodes 0-4): θ = 0.0 rad")
228+
print(f" Group 2 (nodes 5-9): θ = π rad")
229+
print(f" Phase difference: π rad (maximal incompatibility)")
230+
231+
# Connect the groups
232+
net.connect_nodes(0.3, "random")
233+
results_before = net.measure()
234+
print(f" Edges: {net.graph.number_of_edges()}")
235+
print(f" Coherence C(t): {results_before.coherence:.3f}")
236+
237+
# Apply repeated synchronization
238+
print("\nApplying network_sync repeatedly:")
239+
for i in range(3):
240+
net.apply_sequence("network_sync")
241+
phases = [net.graph.nodes[n]['theta'] for n in net.graph.nodes()]
242+
phase_spread = max(phases) - min(phases)
243+
results = net.measure()
244+
print(f" Iteration {i+1}: phase spread = {phase_spread:.3f} rad, C(t) = {results.coherence:.3f}")
245+
246+
results_final = net.measure()
247+
phases_final = [net.graph.nodes[n]['theta'] for n in net.graph.nodes()]
248+
249+
print("\nResults:")
250+
print(f" Final coherence: {results_final.coherence:.3f}")
251+
print(f" Final phase spread: {max(phases_final) - min(phases_final):.3f} rad")
252+
print(f" Coherence gain: {results_final.coherence - results_before.coherence:+.3f}")
253+
print("\n✓ UM successfully merged incompatible phase groups")
254+
255+
return net
256+
257+
258+
def run_all_examples():
259+
"""Run all coupling examples."""
260+
example_1_network_sync()
261+
example_2_coupling_in_connected_network()
262+
example_3_ring_topology_coupling()
263+
example_4_building_from_isolated_nodes()
264+
example_5_phase_group_merging()
265+
266+
print("\n" + "=" * 70)
267+
print("Summary: UM (Coupling) Operator")
268+
print("=" * 70)
269+
print("\nKey Principles:")
270+
print(" 1. Phase Synchronization: θᵢ → θⱼ (primary mechanism)")
271+
print(" 2. EPI Preservation: Each node keeps its structural identity")
272+
print(" 3. Network Formation: Creates coherent relational structure")
273+
print(" 4. Bidirectional: Enables mutual influence and shared coherence")
274+
print()
275+
print("Canonical Sequences Including UM:")
276+
print(" • network_sync: AL → EN → IL → UM → RA → NAV")
277+
print(" Purpose: Full network synchronization cycle")
278+
print(" • Combined with RA: Coupling + propagation = network coherence")
279+
print(" • Combined with IL: Coupling + stabilization = consolidated structure")
280+
print()
281+
print("Use Cases Demonstrated:")
282+
print(" • Phase group synchronization (Example 1)")
283+
print(" • Coupling in existing networks (Example 2)")
284+
print(" • High-structure topology coupling (Example 3)")
285+
print(" • Network formation from scratch (Example 4)")
286+
print(" • Bridging incompatible phases (Example 5)")
287+
print()
288+
print("TNFR Context:")
289+
print(" UM is essential for network-level coherence. Without phase")
290+
print(" synchronization, nodes cannot resonate (RA) or self-organize")
291+
print(" (THOL). UM creates the structural substrate for all collective")
292+
print(" dynamics in TNFR networks.")
293+
print()
294+
print("Real-World Applications:")
295+
print(" • Biomedical: Heart-brain coherence, respiratory coupling")
296+
print(" • Cognitive: Conceptual integration, memory association")
297+
print(" • Social: Team synchronization, cultural transmission")
298+
print(" • Neural: Network formation, synchronized firing patterns")
299+
print()
300+
print("=" * 70)
301+
print("\n✓ All coupling examples completed successfully!")
302+
print()
303+
304+
305+
if __name__ == "__main__":
306+
run_all_examples()

0 commit comments

Comments
 (0)