Merge pull request #2801 from fermga/copilot/add-nu-f-amplification-coherence

RA operator: Add νf amplification, phase alignment strengthening, and network coherence propagation

Author: fermga

src/tnfr/config/defaults_core.py

@@ -86,6 +86,8 @@ class CoreDefaults:
             "UM_vf_sync": 0.10,
             "UM_dnfr_reduction": 0.15,
             "RA_epi_diff": 0.15,
+            "RA_vf_amplification": 0.05,
+            "RA_phase_coupling": 0.10,  # Canonical phase alignment strengthening
             "SHA_vf_factor": 0.85,
             # Conservative scaling (1.05) prevents EPI overflow near boundaries
             # while maintaining meaningful expansion capacity. Critical threshold:

src/tnfr/operators/__init__.py

@@ -768,37 +768,194 @@ def _op_UM(node: NodeProtocol, gf: GlyphFactors) -> None:  # UM — Coupling
 
 
 def _op_RA(node: NodeProtocol, gf: GlyphFactors) -> None:  # RA — Resonance
-    """Diffuse EPI to the node through the Resonance glyph.
+    """Propagate coherence through resonance with νf amplification.
 
-    Resonance propagates EPI along existing couplings without affecting νf,
-    ΔNFR, or phase. The glyph nudges the node towards the neighbour mean using
-    ``RA_epi_diff``.
+    Resonance (RA) propagates EPI along existing couplings while amplifying
+    the structural frequency (νf) to reflect network coherence propagation.
+    According to TNFR theory, RA creates "resonant cascades" where coherence
+    amplifies across the network, increasing collective νf and global C(t).
+
+    **Canonical Effects (always active):**
+
+    - **EPI Propagation**: Diffuses EPI to neighbors (identity-preserving)
+    - **νf Amplification**: Increases structural frequency when propagating coherence
+    - **Phase Alignment**: Strengthens phase synchrony across propagation path
+    - **Network C(t)**: Contributes to global coherence increase
+    - **Identity Preservation**: Maintains structural identity during propagation
 
     Parameters
     ----------
     node : NodeProtocol
         Node harmonising with its neighbourhood.
     gf : GlyphFactors
-        Provides ``RA_epi_diff`` as the mixing coefficient.
+        Provides ``RA_epi_diff`` (mixing coefficient, default 0.15),
+        ``RA_vf_amplification`` (νf boost factor, default 0.05), and
+        ``RA_phase_coupling`` (phase alignment factor, default 0.10).
+
+    Notes
+    -----
+    **νf Amplification (Canonical)**: When neighbors have coherence (|epi_bar| > 1e-9),
+    node.vf is multiplied by (1.0 + RA_vf_amplification). This reflects
+    the canonical TNFR property that resonance amplifies collective νf.
+    This is NOT optional - it is a fundamental property of resonance per TNFR theory.
+
+    **Phase Alignment Strengthening (Canonical)**: RA strengthens phase alignment
+    with neighbors by applying a small phase correction toward the network mean.
+    This ensures that "Phase alignment: Strengthens across propagation path" as
+    stated in the theoretical foundations. Uses existing phase utility functions
+    to avoid code duplication.
+
+    **Network Coherence Tracking (Optional)**: If ``TRACK_NETWORK_COHERENCE`` is enabled,
+    global C(t) is measured before/after RA application to quantify network-level
+    coherence increase.
+
+    **Identity Preservation (Canonical)**: EPI structure (kind and sign) are preserved 
+    during propagation to ensure structural identity is maintained as required by theory.
 
     Examples
     --------
     >>> class MockNode:
     ...     def __init__(self, epi, neighbors):
     ...         self.EPI = epi
     ...         self.epi_kind = "seed"
+    ...         self.vf = 1.0
+    ...         self.theta = 0.0
     ...         self.graph = {}
     ...         self._neighbors = neighbors
     ...     def neighbors(self):
     ...         return self._neighbors
     >>> neighbor = MockNode(1.0, [])
+    >>> neighbor.theta = 0.1
     >>> node = MockNode(0.2, [neighbor])
-    >>> _op_RA(node, {"RA_epi_diff": 0.25})
+    >>> _op_RA(node, {"RA_epi_diff": 0.25, "RA_vf_amplification": 0.05})
     >>> round(node.EPI, 2)
     0.4
+    >>> node.vf  # Amplified due to neighbor coherence (canonical effect)
+    1.05
     """
+    # Get configuration factors
     diff = get_factor(gf, "RA_epi_diff", 0.15)
-    _mix_epi_with_neighbors(node, diff, Glyph.RA)
+    vf_boost = get_factor(gf, "RA_vf_amplification", 0.05)
+    phase_coupling = get_factor(gf, "RA_phase_coupling", 0.10)  # Canonical phase strengthening
+    
+    # Track network C(t) before RA if enabled (optional telemetry)
+    track_coherence = bool(node.graph.get("TRACK_NETWORK_COHERENCE", False))
+    c_before = None
+    if track_coherence and hasattr(node, "G"):
+        try:
+            from ..metrics.coherence import compute_network_coherence
+            c_before = compute_network_coherence(node.G)
+            if "_ra_c_tracking" not in node.graph:
+                node.graph["_ra_c_tracking"] = []
+        except ImportError:
+            pass  # Metrics module not available
+    
+    # Capture state before for metrics
+    vf_before = node.vf
+    epi_before = node.EPI
+    kind_before = node.epi_kind
+    theta_before = node.theta if hasattr(node, "theta") else None
+    
+    # EPI diffusion (existing behavior)
+    neigh, epi_bar = get_neighbor_epi(node)
+    epi_bar_result, kind_result = _mix_epi_with_neighbors(node, diff, Glyph.RA)
+    
+    # CANONICAL EFFECT 1: νf amplification through resonance
+    # This is always active - it's a fundamental property of resonance per TNFR theory
+    # Only amplify if neighbors have coherence to propagate
+    if abs(epi_bar_result) > 1e-9 and len(neigh) > 0:
+        node.vf *= (1.0 + vf_boost)
+    
+    # CANONICAL EFFECT 2: Phase alignment strengthening
+    # Per theory: "Phase alignment: Strengthens across propagation path"
+    # Uses existing phase locking logic from IL operator (avoid duplication)
+    phase_strengthened = False
+    if len(neigh) > 0 and hasattr(node, "theta") and hasattr(node, "G"):
+        try:
+            # Use existing phase locking utility from IL operator
+            from ..alias import get_attr
+            from ..constants.aliases import ALIAS_THETA
+            import cmath
+            import math
+            
+            # Get neighbor phases using existing utilities
+            neighbor_phases = []
+            for n in neigh:
+                try:
+                    theta_n = float(get_attr(n, ALIAS_THETA, 0.0))
+                    neighbor_phases.append(theta_n)
+                except (KeyError, ValueError, TypeError):
+                    continue
+            
+            if neighbor_phases:
+                # Circular mean using the same method as in phase_coherence.py
+                complex_phases = [cmath.exp(1j * theta) for theta in neighbor_phases]
+                mean_real = sum(z.real for z in complex_phases) / len(complex_phases)
+                mean_imag = sum(z.imag for z in complex_phases) / len(complex_phases)
+                mean_complex = complex(mean_real, mean_imag)
+                mean_phase = cmath.phase(mean_complex)
+                
+                # Ensure positive phase [0, 2π]
+                if mean_phase < 0:
+                    mean_phase += 2 * math.pi
+                
+                # Calculate phase difference (shortest arc)
+                delta_theta = mean_phase - node.theta
+                if delta_theta > math.pi:
+                    delta_theta -= 2 * math.pi
+                elif delta_theta < -math.pi:
+                    delta_theta += 2 * math.pi
+                
+                # Apply phase strengthening (move toward network mean)
+                # Same approach as IL operator phase locking
+                node.theta = node.theta + phase_coupling * delta_theta
+                
+                # Normalize to [0, 2π]
+                node.theta = node.theta % (2 * math.pi)
+                phase_strengthened = True
+        except (AttributeError, ImportError):
+            pass  # Phase alignment not possible in this context
+    
+    # Track identity preservation (canonical validation)
+    identity_preserved = (
+        (kind_result == kind_before or kind_result == Glyph.RA.value)
+        and (float(epi_before) * float(node.EPI) >= 0)  # Sign preserved
+    )
+    
+    # Collect propagation metrics if enabled (optional telemetry)
+    collect_metrics = bool(node.graph.get("COLLECT_RA_METRICS", False))
+    if collect_metrics:
+        metrics = {
+            "operator": "RA",
+            "epi_propagated": epi_bar_result,
+            "vf_amplification": node.vf / vf_before if vf_before > 0 else 1.0,
+            "neighbors_influenced": len(neigh),
+            "identity_preserved": identity_preserved,
+            "epi_before": epi_before,
+            "epi_after": float(node.EPI),
+            "vf_before": vf_before,
+            "vf_after": node.vf,
+            "phase_before": theta_before,
+            "phase_after": node.theta if hasattr(node, "theta") else None,
+            "phase_alignment_strengthened": phase_strengthened,
+        }
+        if "ra_metrics" not in node.graph:
+            node.graph["ra_metrics"] = []
+        node.graph["ra_metrics"].append(metrics)
+    
+    # Track network C(t) after RA if enabled (optional telemetry)
+    if track_coherence and c_before is not None and hasattr(node, "G"):
+        try:
+            from ..metrics.coherence import compute_network_coherence
+            c_after = compute_network_coherence(node.G)
+            node.graph["_ra_c_tracking"].append({
+                "node": getattr(node, "n", None),
+                "c_before": c_before,
+                "c_after": c_after,
+                "c_delta": c_after - c_before,
+            })
+        except ImportError:
+            pass
 
 
 def _op_SHA(node: NodeProtocol, gf: GlyphFactors) -> None:  # SHA — Silence

src/tnfr/operators/definitions.py

@@ -1663,10 +1663,15 @@ def _validate_preconditions(self, G: TNFRGraph, node: Any) -> None:
     def _collect_metrics(
         self, G: TNFRGraph, node: Any, state_before: dict[str, Any]
     ) -> dict[str, Any]:
-        """Collect RA-specific metrics."""
+        """Collect RA-specific metrics with canonical νf amplification tracking."""
         from .metrics import resonance_metrics
 
-        return resonance_metrics(G, node, state_before["epi"])
+        return resonance_metrics(
+            G, 
+            node, 
+            state_before["epi"],
+            vf_before=state_before["vf"]  # Include νf for amplification tracking
+        )
 
 
 @register_operator

src/tnfr/operators/metrics.py

@@ -747,8 +747,20 @@ def coupling_metrics(
     return metrics
 
 
-def resonance_metrics(G: TNFRGraph, node: NodeId, epi_before: float) -> dict[str, Any]:
-    """RA - Resonance metrics: EPI propagation, affected neighbors, resonance strength.
+def resonance_metrics(
+    G: TNFRGraph, 
+    node: NodeId, 
+    epi_before: float,
+    vf_before: float | None = None,
+) -> dict[str, Any]:
+    """RA - Resonance metrics: EPI propagation, νf amplification, phase strengthening.
+
+    Canonical TNFR resonance metrics include:
+    - EPI propagation effectiveness
+    - νf amplification (structural frequency increase)
+    - Phase alignment strengthening
+    - Identity preservation validation
+    - Network coherence contribution
 
     Parameters
     ----------
@@ -758,13 +770,21 @@ def resonance_metrics(G: TNFRGraph, node: NodeId, epi_before: float) -> dict[str
         Node to collect metrics from
     epi_before : float
         EPI value before operator application
+    vf_before : float | None
+        νf value before operator application (for amplification tracking)
 
     Returns
     -------
     dict
-        Resonance-specific metrics including propagation effectiveness
+        Resonance-specific metrics including:
+        - EPI propagation metrics
+        - νf amplification ratio (canonical effect)
+        - Phase alignment quality
+        - Identity preservation status
+        - Network coherence contribution
     """
     epi_after = _get_node_attr(G, node, ALIAS_EPI)
+    vf_after = _get_node_attr(G, node, ALIAS_VF)
     neighbors = list(G.neighbors(node))
     neighbor_count = len(neighbors)
 
@@ -773,20 +793,42 @@ def resonance_metrics(G: TNFRGraph, node: NodeId, epi_before: float) -> dict[str
         neighbor_epi_sum = sum(_get_node_attr(G, n, ALIAS_EPI) for n in neighbors)
         neighbor_epi_mean = neighbor_epi_sum / neighbor_count
         resonance_strength = abs(epi_after - epi_before) * neighbor_count
+        
+        # Canonical νf amplification tracking
+        if vf_before is not None and vf_before > 0:
+            vf_amplification = vf_after / vf_before
+        else:
+            vf_amplification = 1.0
+            
+        # Phase alignment quality (measure coherence with neighbors)
+        from ..metrics.phase_coherence import compute_phase_alignment
+        phase_alignment = compute_phase_alignment(G, node)
     else:
         neighbor_epi_mean = 0.0
         resonance_strength = 0.0
+        vf_amplification = 1.0
+        phase_alignment = 0.0
+
+    # Identity preservation check (sign should be preserved)
+    identity_preserved = (epi_before * epi_after >= 0)
 
     return {
         "operator": "Resonance",
         "glyph": "RA",
         "delta_epi": epi_after - epi_before,
         "epi_final": epi_after,
+        "epi_before": epi_before,
         "neighbor_count": neighbor_count,
         "neighbor_epi_mean": neighbor_epi_mean,
         "resonance_strength": resonance_strength,
         "propagation_successful": neighbor_count > 0
         and abs(epi_after - neighbor_epi_mean) < 0.5,
+        # Canonical TNFR effects
+        "vf_amplification": vf_amplification,  # Canonical: νf increases through resonance
+        "vf_before": vf_before if vf_before is not None else vf_after,
+        "vf_after": vf_after,
+        "phase_alignment": phase_alignment,  # Canonical: phase strengthens
+        "identity_preserved": identity_preserved,  # Canonical: EPI identity maintained
     }