Merge pull request #2813 from fermga/copilot/implement-sub-epi-propagation

Implement THOL sub-EPI network propagation and cascade dynamics

Author: fermga

src/tnfr/config/defaults_core.py

@@ -141,6 +141,12 @@ class CoreDefaults:
     THOL_METABOLIC_COMPLEXITY_WEIGHT: float = 0.10
     THOL_BIFURCATION_THRESHOLD: float = 0.1
 
+    # THOL network propagation and cascade parameters
+    THOL_PROPAGATION_ENABLED: bool = True
+    THOL_MIN_COUPLING_FOR_PROPAGATION: float = 0.5
+    THOL_PROPAGATION_ATTENUATION: float = 0.7
+    THOL_CASCADE_MIN_NODES: int = 3
+
 
 @dataclass(frozen=True, slots=True)
 class RemeshDefaults:

src/tnfr/operators/cascade.py

@@ -0,0 +1,165 @@
+"""Cascade detection and analysis for THOL self-organization.
+
+Provides tools to detect, measure, and analyze emergent cascades in
+TNFR networks where THOL bifurcations propagate through coupled nodes.
+
+TNFR Canonical Principle
+-------------------------
+From "El pulso que nos atraviesa" (TNFR Manual, §2.2.10):
+
+    "THOL actúa como modulador central de plasticidad. Es el glifo que
+    permite a la red reorganizar su topología sin intervención externa.
+    Su activación crea bucles de aprendizaje resonante, trayectorias de
+    reorganización emergente, estabilidad dinámica basada en coherencia local."
+
+This module implements cascade detection: when THOL bifurcations propagate
+through phase-aligned neighbors, creating chains of emergent reorganization.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..types import NodeId, TNFRGraph
+
+__all__ = [
+    "detect_cascade",
+    "measure_cascade_radius",
+]
+
+
+def detect_cascade(G: TNFRGraph) -> dict[str, Any]:
+    """Detect if THOL triggered a propagation cascade in the network.
+
+    A cascade is defined as a chain reaction where:
+    1. Node A bifurcates (THOL)
+    2. Sub-EPI propagates to coupled neighbors
+    3. Neighbors' EPIs increase, potentially triggering their own bifurcations
+    4. Process continues across ≥3 nodes
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph with THOL propagation history
+
+    Returns
+    -------
+    dict
+        Cascade analysis containing:
+        - is_cascade: bool (True if cascade detected)
+        - affected_nodes: set of NodeIds involved
+        - cascade_depth: maximum propagation chain length
+        - total_propagations: total number of propagation events
+        - cascade_coherence: average coupling strength in cascade
+
+    Notes
+    -----
+    TNFR Principle: Cascades emerge when network phase coherence enables
+    propagation across multiple nodes, creating collective self-organization.
+
+    Examples
+    --------
+    >>> # Network with cascade
+    >>> analysis = detect_cascade(G)
+    >>> analysis["is_cascade"]
+    True
+    >>> analysis["cascade_depth"]
+    4  # Propagated through 4 levels
+    >>> len(analysis["affected_nodes"])
+    7  # 7 nodes affected
+    """
+    propagations = G.graph.get("thol_propagations", [])
+
+    if not propagations:
+        return {
+            "is_cascade": False,
+            "affected_nodes": set(),
+            "cascade_depth": 0,
+            "total_propagations": 0,
+            "cascade_coherence": 0.0,
+        }
+
+    # Build propagation graph
+    affected_nodes = set()
+    for prop in propagations:
+        affected_nodes.add(prop["source_node"])
+        for target, _ in prop["propagations"]:
+            affected_nodes.add(target)
+
+    # Compute cascade depth (longest propagation chain)
+    # For now, approximate as number of propagation events
+    cascade_depth = len(propagations)
+
+    # Total propagations
+    total_props = sum(len(p["propagations"]) for p in propagations)
+
+    # Get cascade minimum nodes from config
+    cascade_min_nodes = int(G.graph.get("THOL_CASCADE_MIN_NODES", 3))
+
+    # Cascade = affects ≥ cascade_min_nodes
+    is_cascade = len(affected_nodes) >= cascade_min_nodes
+
+    return {
+        "is_cascade": is_cascade,
+        "affected_nodes": affected_nodes,
+        "cascade_depth": cascade_depth,
+        "total_propagations": total_props,
+        "cascade_coherence": 0.0,  # TODO: compute from coupling strengths
+    }
+
+
+def measure_cascade_radius(G: TNFRGraph, source_node: NodeId) -> int:
+    """Measure propagation radius from bifurcation source.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph with propagation history
+    source_node : NodeId
+        Origin node of cascade
+
+    Returns
+    -------
+    int
+        Number of nodes reached by propagation (hop distance)
+
+    Notes
+    -----
+    Uses BFS to trace propagation paths from source.
+
+    Examples
+    --------
+    >>> # Linear cascade: 0 -> 1 -> 2 -> 3
+    >>> radius = measure_cascade_radius(G, source_node=0)
+    >>> radius
+    3  # Reached 3 hops from source
+    """
+    propagations = G.graph.get("thol_propagations", [])
+
+    # Build propagation edges from this source
+    prop_edges = []
+    for prop in propagations:
+        if prop["source_node"] == source_node:
+            for target, _ in prop["propagations"]:
+                prop_edges.append((source_node, target))
+
+    if not prop_edges:
+        return 0
+
+    # BFS to measure radius
+    visited = {source_node}
+    queue = deque([(source_node, 0)])  # (node, distance)
+    max_distance = 0
+
+    while queue:
+        current, dist = queue.popleft()
+        max_distance = max(max_distance, dist)
+
+        for src, tgt in prop_edges:
+            if src == current and tgt not in visited:
+                visited.add(tgt)
+                queue.append((tgt, dist + 1))
+
+    return max_distance

src/tnfr/operators/definitions.py

@@ -2632,6 +2632,23 @@ def _spawn_sub_epi(
         new_epi = parent_epi + sub_epi_value * _THOL_EMERGENCE_CONTRIBUTION
         set_attr(G.nodes[node], ALIAS_EPI, new_epi)
 
+        # CANONICAL PROPAGATION: Enable network cascade dynamics
+        if G.graph.get("THOL_PROPAGATION_ENABLED", True):
+            from .metabolism import propagate_subepi_to_network
+
+            propagations = propagate_subepi_to_network(G, node, sub_epi_record)
+
+            # Record propagation telemetry for cascade analysis
+            if propagations:
+                G.graph.setdefault("thol_propagations", []).append(
+                    {
+                        "source_node": node,
+                        "sub_epi": sub_epi_value,
+                        "propagations": propagations,
+                        "timestamp": timestamp,
+                    }
+                )
+
     def _validate_preconditions(self, G: TNFRGraph, node: Any) -> None:
         """Validate THOL-specific preconditions."""
         from .preconditions import validate_self_organization

src/tnfr/operators/metabolism.py

@@ -45,6 +45,7 @@
 __all__ = [
     "capture_network_signals",
     "metabolize_signals_into_subepi",
+    "propagate_subepi_to_network",
 ]
 
 
@@ -219,3 +220,112 @@ def metabolize_signals_into_subepi(
 
     # Structural bounds [0, 1]
     return float(np.clip(metabolized_epi, 0.0, 1.0))
+
+
+def propagate_subepi_to_network(
+    G: TNFRGraph,
+    parent_node: NodeId,
+    sub_epi_record: dict[str, Any],
+) -> list[tuple[NodeId, float]]:
+    """Propagate emergent sub-EPI to coupled neighbors through resonance.
+
+    Implements canonical THOL network dynamics: bifurcation creates structures
+    that propagate through coupled nodes, triggering potential cascades.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the network
+    parent_node : NodeId
+        Node where sub-EPI originated (bifurcation source)
+    sub_epi_record : dict
+        Sub-EPI record from bifurcation, containing:
+        - "epi": sub-EPI magnitude
+        - "vf": inherited structural frequency
+        - "timestamp": creation time
+
+    Returns
+    -------
+    list of (NodeId, float)
+        List of (neighbor_id, injected_epi) tuples showing propagation results.
+        Empty list if no propagation occurred.
+
+    Notes
+    -----
+    TNFR Principle: "Sub-EPIs propagate to coupled neighbors, triggering their
+    own bifurcations when ∂²EPI/∂t² > τ" (canonical THOL dynamics).
+
+    Propagation mechanism:
+    1. Select neighbors with sufficient coupling (phase alignment)
+    2. Compute attenuation based on coupling strength
+    3. Inject attenuated sub-EPI influence into neighbor's EPI
+    4. Record propagation in graph telemetry
+
+    Attenuation prevents unbounded growth while enabling cascades.
+
+    Examples
+    --------
+    >>> # Create coupled network
+    >>> G = nx.Graph()
+    >>> G.add_node(0, epi=0.50, vf=1.0, theta=0.1)
+    >>> G.add_node(1, epi=0.40, vf=1.0, theta=0.12)  # Phase-aligned
+    >>> G.add_edge(0, 1)
+    >>> sub_epi = {"epi": 0.15, "vf": 1.1, "timestamp": 10}
+    >>> propagations = propagate_subepi_to_network(G, node=0, sub_epi_record=sub_epi)
+    >>> len(propagations)  # Number of neighbors reached
+    1
+    >>> propagations[0]  # (neighbor_id, injected_epi)
+    (1, 0.105)  # 70% attenuation
+    """
+    from ..alias import set_attr
+    from ..utils.numeric import angle_diff
+
+    neighbors = list(G.neighbors(parent_node))
+    if not neighbors:
+        return []
+
+    # Configuration
+    min_coupling_strength = float(
+        G.graph.get("THOL_MIN_COUPLING_FOR_PROPAGATION", 0.5)
+    )
+    attenuation_factor = float(G.graph.get("THOL_PROPAGATION_ATTENUATION", 0.7))
+
+    parent_theta = float(get_attr(G.nodes[parent_node], ALIAS_THETA, 0.0))
+    sub_epi_magnitude = sub_epi_record["epi"]
+
+    propagations = []
+
+    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)
+
+        # Propagate only if sufficiently coupled
+        if coupling_strength >= min_coupling_strength:
+            # Attenuate sub-EPI based on distance and coupling
+            attenuated_epi = (
+                sub_epi_magnitude * attenuation_factor * coupling_strength
+            )
+
+            # Inject into neighbor's EPI
+            neighbor_epi = float(get_attr(G.nodes[neighbor], ALIAS_EPI, 0.0))
+            new_neighbor_epi = neighbor_epi + attenuated_epi
+
+            # Boundary check
+            from ..dynamics.structural_clip import structural_clip
+
+            epi_max = float(G.graph.get("EPI_MAX", 1.0))
+            new_neighbor_epi = structural_clip(new_neighbor_epi, lo=0.0, hi=epi_max)
+
+            set_attr(G.nodes[neighbor], ALIAS_EPI, new_neighbor_epi)
+
+            propagations.append((neighbor, attenuated_epi))
+
+            # Update neighbor's EPI history for potential subsequent bifurcation
+            history = G.nodes[neighbor].get("epi_history", [])
+            history.append(new_neighbor_epi)
+            G.nodes[neighbor]["epi_history"] = history[-10:]  # Keep last 10
+
+    return propagations

src/tnfr/operators/metrics.py

@@ -990,6 +990,8 @@ def self_organization_metrics(
     dict
         Self-organization-specific metrics including cascade indicators
     """
+    from .cascade import detect_cascade, measure_cascade_radius
+
     epi_after = _get_node_attr(G, node, ALIAS_EPI)
     vf_after = _get_node_attr(G, node, ALIAS_VF)
     d2epi = _get_node_attr(G, node, ALIAS_D2EPI)
@@ -998,6 +1000,15 @@ def self_organization_metrics(
     # Track nested EPI count if graph maintains it
     nested_epi_count = len(G.graph.get("sub_epi", []))
 
+    # NEW: Network propagation and cascade metrics
+    cascade_analysis = detect_cascade(G)
+    cascade_radius = (
+        measure_cascade_radius(G, node) if cascade_analysis["is_cascade"] else 0
+    )
+
+    propagations = G.graph.get("thol_propagations", [])
+    propagated = len(propagations) > 0
+
     return {
         "operator": "Self-organization",
         "glyph": "THOL",
@@ -1009,6 +1020,12 @@ def self_organization_metrics(
         "dnfr_final": dnfr,
         "nested_epi_count": nested_epi_count,
         "cascade_active": abs(d2epi) > 0.1,  # Configurable threshold
+        # NEW: Network emergence metrics
+        "propagated": propagated,
+        "cascade_detected": cascade_analysis["is_cascade"],
+        "cascade_radius": cascade_radius,
+        "affected_node_count": len(cascade_analysis["affected_nodes"]),
+        "total_propagations": cascade_analysis["total_propagations"],
     }