Merge pull request #2797 from fermga/copilot/test-epi-invariance-validation

Validate and document EPI invariance for UM (Coupling) operator

Author: fermga

docs/source/user-guide/OPERATORS_GUIDE.md

@@ -234,6 +234,17 @@ print(f"ΔNFR after coupling: {dnfr1:.3f} (reduced by mutual stabilization)")
 - Preserves existing couplings
 - Respects nodal equation: ∂EPI/∂t = νf · ΔNFR(t)
 
+**Structural Invariants**:
+- **⚠️ CRITICAL**: UM **NEVER** modifies EPI directly
+- EPI identity is preserved during all coupling operations
+- Only θ (phase), νf (frequency), and ΔNFR are modified by UM
+- Any EPI change during a sequence with UM must come from:
+  - Other operators (Emission, Reception, etc.)
+  - Natural evolution via nodal equation: ∂EPI/∂t = νf · ΔNFR(t)
+  - Never from UM itself
+- Theoretical basis: Coupling creates structural links through phase synchronization (φᵢ(t) ≈ φⱼ(t)), not through information transfer or EPI modification
+- Implementation guarantee: `_op_UM` function does not touch EPI attributes
+
 **Notes**:
 According to TNFR canonical theory, coupling synchronizes not only phases but also
 structural frequencies, and produces a stabilizing effect that reduces reorganization

src/tnfr/operators/definitions.py

@@ -1366,6 +1366,30 @@ class Coupling(Operator):
     Set ``VALIDATE_OPERATOR_PRECONDITIONS=True`` in graph metadata to enable validation.
     Validation is backward-compatible and disabled by default to preserve existing behavior.
 
+    Structural Invariants
+    ---------------------
+    **CRITICAL**: UM preserves EPI identity. The coupling process synchronizes
+    phases (θ), may align structural frequencies (νf), and can reduce ΔNFR, but
+    it NEVER directly modifies EPI. This ensures that coupled nodes maintain
+    their structural identities while achieving phase coherence.
+    
+    Any change to EPI during a sequence containing UM must come from other
+    operators (e.g., Emission, Reception) or from the natural evolution via
+    the nodal equation ∂EPI/∂t = νf · ΔNFR(t), never from UM itself.
+    
+    **Theoretical Basis**: In TNFR theory, coupling (UM) creates structural links 
+    through phase synchronization φᵢ(t) ≈ φⱼ(t), not through information transfer 
+    or EPI modification. The structural identity (EPI) of each node remains intact 
+    while the nodes achieve synchronized phases that enable resonant interaction.
+    
+    **Implementation Guarantee**: The `_op_UM` function modifies only:
+    
+    - Phase (θ): Adjusted towards consensus phase
+    - Structural frequency (νf): Optionally synchronized with neighbors
+    - Reorganization gradient (ΔNFR): Reduced through stabilization
+    
+    EPI is never touched by the coupling logic, preserving this fundamental invariant.
+
     Structural Effects
     ------------------
     - **θ**: Phases of coupled nodes converge (primary effect)
@@ -1476,6 +1500,7 @@ def _collect_metrics(
             dnfr_before=state_before["dnfr"],
             vf_before=state_before["vf"],
             edges_before=state_before.get("edges", None),
+            epi_before=state_before["epi"],
         )
 
 

src/tnfr/operators/metrics.py

@@ -559,6 +559,7 @@ def coupling_metrics(
     dnfr_before: float = None,
     vf_before: float = None,
     edges_before: int = None,
+    epi_before: float = None,
 ) -> dict[str, Any]:
     """UM - Coupling metrics: phase alignment, link formation, synchrony, ΔNFR reduction.
 
@@ -579,6 +580,8 @@ def coupling_metrics(
         Structural frequency (νf) before operator application
     edges_before : int, optional
         Number of edges before operator application
+    epi_before : float, optional
+        EPI value before operator application (for invariance verification)
 
     Returns
     -------
@@ -607,6 +610,13 @@ def coupling_metrics(
         - dnfr_reduction: Absolute reduction (before - after)
         - dnfr_reduction_pct: Percentage reduction
         
+        **EPI Invariance metrics:**
+        
+        - epi_before: EPI value before coupling
+        - epi_after: EPI value after coupling
+        - epi_drift: Absolute difference between before and after
+        - epi_preserved: Boolean indicating EPI invariance (drift < 1e-9)
+        
         **Network metrics:**
         
         - neighbor_count: Number of neighbors after coupling
@@ -622,6 +632,10 @@ def coupling_metrics(
     capture both the synchronization quality and the network structural changes
     resulting from coupling.
     
+    **EPI Invariance**: UM MUST preserve EPI identity. The epi_preserved metric
+    validates this fundamental invariant. If epi_preserved is False, it indicates
+    a violation of TNFR canonical requirements.
+    
     See Also
     --------
     operators.definitions.Coupling : UM operator implementation
@@ -679,6 +693,18 @@ def coupling_metrics(
             "dnfr_final": dnfr_after,
         })
 
+    # EPI invariance verification (if epi_before provided)
+    # CRITICAL: UM MUST preserve EPI identity per TNFR canonical theory
+    if epi_before is not None:
+        epi_after = _get_node_attr(G, node, ALIAS_EPI)
+        epi_drift = abs(epi_after - epi_before)
+        metrics.update({
+            "epi_before": epi_before,
+            "epi_after": epi_after,
+            "epi_drift": epi_drift,
+            "epi_preserved": epi_drift < 1e-9,  # Should ALWAYS be True
+        })
+
     # Edge/network formation metrics (if edges_before provided)
     edges_after = G.degree(node)
     if edges_before is not None:

tests/unit/dynamics/test_operator_factors.py

@@ -16,7 +16,7 @@ def test_get_factor_returns_float():
 
 
 def test_op_al_uses_factor():
-    node = SimpleNamespace(EPI=1.0, graph={})
+    node = SimpleNamespace(EPI=1.0, graph={"EPI_MAX": 2.0})
     gf = {"AL_boost": "0.2"}
     operators._op_AL(node, gf)
     assert node.EPI == pytest.approx(1.2)
@@ -27,7 +27,7 @@ def test_op_en_uses_mix():
     node = SimpleNamespace(
         EPI=1.0,
         epi_kind="self",
-        graph={},
+        graph={"EPI_MAX": 20.0},
         neighbors=lambda: [neigh],
     )
     gf = {"EN_mix": "0.5"}
@@ -73,6 +73,7 @@ def test_op_oz_ignores_noise_with_non_positive_sigma():
 
 def test_op_um_uses_theta_push(graph_canon):
     G = graph_canon()
+    G.graph["UM_BIDIRECTIONAL"] = False  # Use legacy unidirectional mode for this test
     G.add_node(0, **{"theta": 0.0, "EPI": 0.0, "Si": 0.0})
     G.add_node(1, **{"theta": 1.0, "EPI": 0.0, "Si": 0.0})
     G.add_edge(0, 1)
@@ -87,7 +88,7 @@ def test_op_ra_uses_diff():
     node = SimpleNamespace(
         EPI=0.0,
         epi_kind="",
-        graph={},
+        graph={"EPI_MAX": 20.0},
         neighbors=lambda: [neigh],
     )
     gf = {"RA_epi_diff": "0.5"}
@@ -104,14 +105,14 @@ def test_op_sha_uses_factor():
 
 
 def test_scale_ops_use_factor_val():
-    node = SimpleNamespace(vf=3.0, graph={})
+    node = SimpleNamespace(vf=3.0, EPI=1.0, graph={"EDGE_AWARE_ENABLED": False})
     gf = {"VAL_scale": "2.0"}
     operators.GLYPH_OPERATIONS[Glyph.VAL](node, gf)
     assert node.vf == pytest.approx(6.0)
 
 
 def test_scale_ops_use_factor_nul():
-    node = SimpleNamespace(vf=3.0, graph={})
+    node = SimpleNamespace(vf=3.0, EPI=1.0, graph={"EDGE_AWARE_ENABLED": False})
     gf = {"NUL_scale": "0.5"}
     operators.GLYPH_OPERATIONS[Glyph.NUL](node, gf)
     assert node.vf == pytest.approx(1.5)

tests/unit/dynamics/test_operators.py

@@ -6,7 +6,7 @@
 import pytest
 
 import tnfr.operators as operators
-from tnfr.constants import DNFR_PRIMARY, THETA_PRIMARY, inject_defaults
+from tnfr.constants import DNFR_PRIMARY, EPI_PRIMARY, THETA_PRIMARY, inject_defaults
 from tnfr.dynamics import set_delta_nfr_hook
 from tnfr.node import NodeNX
 from tnfr.operators import (
@@ -18,6 +18,7 @@
     reset_jitter_manager,
     _um_candidate_iter,
 )
+from tnfr.operators.definitions import Coupling
 from tnfr.validation import SequenceValidationResult
 from tnfr.structural import Dissonance, create_nfr, run_sequence
 from tnfr.types import Glyph
@@ -361,3 +362,71 @@ def test_um_coupling_wraps_phases_near_pi_boundary(graph_canon):
     new_theta = G.nodes[0]["theta"]
     assert new_theta == pytest.approx(expected_theta)
     assert -math.pi <= new_theta < math.pi
+
+
+def test_um_preserves_epi_identity():
+    """Verify that UM does not directly modify EPI.
+    
+    One of the fundamental principles of the UM (Coupling) operator is that it 
+    preserves the identity EPI of nodes during coupling. The coupling process 
+    synchronizes θ (phase) and potentially νf (structural frequency), but NEVER 
+    modifies EPI directly. This test validates this critical invariant.
+    """
+    # Create two nodes with different EPI and phase values
+    G, node1 = create_nfr("node1", epi=0.5, theta=0.0)
+    G, node2 = create_nfr("node2", epi=0.7, theta=math.pi/4, graph=G)
+    G.add_edge(node1, node2)
+    
+    # Record EPI values before applying UM
+    epi_before_node1 = G.nodes[node1][EPI_PRIMARY]
+    epi_before_node2 = G.nodes[node2][EPI_PRIMARY]
+    
+    # Apply UM (Coupling) operator to node1
+    Coupling()(G, node1)
+    
+    # Get EPI values after applying UM
+    epi_after_node1 = G.nodes[node1][EPI_PRIMARY]
+    epi_after_node2 = G.nodes[node2][EPI_PRIMARY]
+    
+    # EPI should be unchanged for both the node and its neighbor
+    # Use strict tolerance (1e-9) to ensure no modification occurred
+    assert abs(epi_after_node1 - epi_before_node1) < 1e-9, \
+        f"UM modified node1 EPI: {epi_before_node1} → {epi_after_node1}"
+    assert abs(epi_after_node2 - epi_before_node2) < 1e-9, \
+        f"UM modified node2 EPI: {epi_before_node2} → {epi_after_node2}"
+    
+    # Verify the exact values remained constant
+    assert epi_after_node1 == 0.5, "node1 EPI should remain 0.5"
+    assert epi_after_node2 == 0.7, "node2 EPI should remain 0.7"
+
+
+def test_um_preserves_epi_identity_with_multiple_neighbors():
+    """Verify EPI preservation when coupling a node with multiple neighbors.
+    
+    Tests that UM maintains EPI identity even in complex network configurations
+    where a node couples with multiple neighbors simultaneously.
+    """
+    # Create a central node with multiple neighbors
+    G, center = create_nfr("center", epi=0.6, theta=0.0)
+    neighbors = []
+    for i in range(4):
+        G, neighbor = create_nfr(f"neighbor_{i}", epi=0.5 + i*0.1, theta=i*math.pi/4, graph=G)
+        G.add_edge(center, neighbor)
+        neighbors.append(neighbor)
+    
+    # Record all EPI values before coupling
+    epi_before = {center: G.nodes[center][EPI_PRIMARY]}
+    for n in neighbors:
+        epi_before[n] = G.nodes[n][EPI_PRIMARY]
+    
+    # Apply UM to the central node
+    Coupling()(G, center)
+    
+    # Verify EPI unchanged for center node and all neighbors
+    assert abs(G.nodes[center][EPI_PRIMARY] - epi_before[center]) < 1e-9, \
+        f"UM modified center EPI: {epi_before[center]} → {G.nodes[center][EPI_PRIMARY]}"
+    
+    for n in neighbors:
+        epi_after = G.nodes[n][EPI_PRIMARY]
+        assert abs(epi_after - epi_before[n]) < 1e-9, \
+            f"UM modified {n} EPI: {epi_before[n]} → {epi_after}"