Refactor UM and THOL operators to use unified phase compatibility functions

Co-authored-by: fermga <203334638+fermga@users.noreply.github.com>

Author: Copilot

src/tnfr/metrics/__init__.py

@@ -32,6 +32,11 @@
     compute_learning_plasticity,
     glyph_history_to_operator_names,
 )
+from .phase_compatibility import (
+    compute_network_phase_alignment,
+    compute_phase_coupling_strength,
+    is_phase_compatible,
+)
 from .reporting import (
     Tg_by_node,
     Tg_global,
@@ -68,4 +73,7 @@
     "compute_bifurcation_rate",
     "compute_metabolic_efficiency",
     "compute_emergence_index",
+    "compute_phase_coupling_strength",
+    "is_phase_compatible",
+    "compute_network_phase_alignment",
 )

src/tnfr/operators/__init__.py

@@ -741,10 +741,11 @@ def _op_UM(node: NodeProtocol, gf: GlyphFactors) -> None:  # UM — Coupling
 
                 # Compute phase alignments with each neighbor
                 phase_alignments = []
+                # Compute phase alignment using canonical formula
+                from ..metrics.phase_compatibility import compute_phase_coupling_strength
+                
                 for neighbor in neighbors:
-                    dphi = abs(angle_diff(neighbor.theta, node.theta))
-                    # alignment: 1.0 (perfectly aligned) to 0.0 (opposite phases)
-                    alignment = 1.0 - dphi / math.pi
+                    alignment = compute_phase_coupling_strength(node.theta, neighbor.theta)
                     phase_alignments.append(alignment)
 
                 # Mean alignment represents coupling strength
@@ -772,13 +773,17 @@ def _op_UM(node: NodeProtocol, gf: GlyphFactors) -> None:  # UM — Coupling
         )
 
         for j in candidates:
-            th_j = j.theta
-            dphi = abs(angle_diff(th_j, th_i)) / math.pi
+            # Use canonical phase coupling strength formula
+            from ..metrics.phase_compatibility import compute_phase_coupling_strength
+            
+            phase_coupling = compute_phase_coupling_strength(th_i, j.theta)
+            
             epi_j = j.EPI
             si_j = j.Si
             epi_sim = 1.0 - abs(epi_i - epi_j) / (abs(epi_i) + abs(epi_j) + 1e-9)
             si_sim = 1.0 - abs(si_i - si_j)
-            compat = (1 - dphi) * 0.5 + 0.25 * epi_sim + 0.25 * si_sim
+            # Compatibility combines phase coupling (50%), EPI similarity (25%), Si similarity (25%)
+            compat = phase_coupling * 0.5 + 0.25 * epi_sim + 0.25 * si_sim
             if compat >= thr:
                 node.add_edge(j, compat)
 

src/tnfr/operators/metabolism.py

@@ -97,6 +97,7 @@ def capture_network_signals(G: TNFRGraph, node: NodeId) -> dict[str, Any] | None
     0.45
     """
     np = get_numpy()
+    from ..metrics.phase_compatibility import compute_phase_coupling_strength
 
     neighbors = list(G.neighbors(node))
     if not neighbors:
@@ -117,12 +118,9 @@ def capture_network_signals(G: TNFRGraph, node: NodeId) -> dict[str, Any] | None
         neighbor_epis.append(n_epi)
         neighbor_thetas.append(n_theta)
 
-        # Coupling strength based on phase alignment
-        phase_diff = abs(n_theta - node_theta)
-        # Normalize to [0, π]
-        if phase_diff > math.pi:
-            phase_diff = 2 * math.pi - phase_diff
-        coupling_strength = 1.0 - (phase_diff / math.pi)
+        # Coupling strength using canonical phase compatibility formula
+        # (unified across UM, RA, THOL operators - see phase_compatibility module)
+        coupling_strength = compute_phase_coupling_strength(node_theta, n_theta)
         coupling_strengths.append(coupling_strength)
 
     # Compute structural gradients
@@ -282,7 +280,7 @@ def propagate_subepi_to_network(
     (1, 0.105)  # 70% attenuation
     """
     from ..alias import set_attr
-    from ..utils.numeric import angle_diff
+    from ..metrics.phase_compatibility import compute_phase_coupling_strength
 
     neighbors = list(G.neighbors(parent_node))
     if not neighbors:
@@ -300,9 +298,9 @@ def propagate_subepi_to_network(
     for neighbor in neighbors:
         neighbor_theta = float(get_attr(G.nodes[neighbor], ALIAS_THETA, 0.0))
 
-        # Compute coupling strength (phase alignment)
-        phase_diff = abs(angle_diff(neighbor_theta, parent_theta))
-        coupling_strength = 1.0 - (phase_diff / math.pi)
+        # Compute coupling strength using canonical phase compatibility formula
+        # (unified across UM, RA, THOL operators - see phase_compatibility module)
+        coupling_strength = compute_phase_coupling_strength(parent_theta, neighbor_theta)
 
         # Propagate only if sufficiently coupled
         if coupling_strength >= min_coupling_strength: