tnfr 3.0.3__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/metrics/learning_metrics.py

@@ -0,0 +1,280 @@
+"""Learning metrics for adaptive TNFR dynamics.
+
+This module provides metrics specific to adaptive learning processes,
+measuring plasticity, consolidation, and learning efficiency using
+existing TNFR infrastructure (glyph history, EPI, νf, ΔNFR).
+
+All functions reuse canonical utilities from glyph_history and alias modules.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_EPI, ALIAS_VF, ALIAS_DNFR
+from ..glyph_history import ensure_history, count_glyphs
+from ..types import TNFRGraph, Glyph
+from ..config.operator_names import (
+    COHERENCE,
+    DISSONANCE,
+    EMISSION,
+    MUTATION,
+    RECEPTION,
+    RECURSIVITY,
+    SELF_ORGANIZATION,
+    SILENCE,
+)
+
+__all__ = [
+    "compute_learning_plasticity",
+    "compute_consolidation_index",
+    "compute_learning_efficiency",
+    "glyph_history_to_operator_names",
+]
+
+
+def glyph_history_to_operator_names(glyph_history: Sequence[str]) -> list[str]:
+    """Convert glyph history to operator names for comparison.
+
+    This is a lightweight helper that converts glyphs (e.g., 'AL', 'EN') to
+    canonical operator names (e.g., 'emission', 'reception') using the
+    existing GLYPH_TO_FUNCTION mapping.
+
+    Parameters
+    ----------
+    glyph_history : Sequence[str]
+        Sequence of glyph codes from node's glyph_history.
+
+    Returns
+    -------
+    list[str]
+        List of canonical operator names.
+
+    Notes
+    -----
+    Reuses existing GLYPH_TO_FUNCTION mapping from grammar module.
+    Computational cost is O(n) with n = len(glyph_history), just dict lookups.
+
+    Examples
+    --------
+    >>> from tnfr.metrics.learning_metrics import glyph_history_to_operator_names
+    >>> glyphs = ['AL', 'EN', 'IL']
+    >>> names = glyph_history_to_operator_names(glyphs)
+    >>> names
+    ['emission', 'reception', 'coherence']
+    """
+    from ..operators.grammar import GLYPH_TO_FUNCTION
+
+    result = []
+    for glyph_str in glyph_history:
+        # Convert string to Glyph enum if needed
+        try:
+            glyph = Glyph(glyph_str)
+            operator_name = GLYPH_TO_FUNCTION.get(glyph, glyph_str.lower())
+            result.append(operator_name)
+        except (ValueError, KeyError):
+            # If glyph is not recognized, keep as-is lowercased
+            result.append(glyph_str.lower())
+
+    return result
+
+
+def compute_learning_plasticity(
+    G: TNFRGraph,
+    node: Any,
+    window: int = 10,
+) -> float:
+    """Measure capacity for structural reorganization (learning plasticity).
+
+    High plasticity indicates high capacity for learning and adaptation.
+    Plasticity is measured by the frequency of reorganization operators
+    (OZ, THOL, ZHIR) in the recent glyph history.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph storing TNFR nodes and their structural operator history.
+    node : Any
+        Node identifier within G.
+    window : int, default=10
+        Number of recent glyphs to analyze.
+
+    Returns
+    -------
+    float
+        Plasticity index in range [0.0, 1.0] where higher values indicate
+        greater reorganization capacity.
+
+    Notes
+    -----
+    Reuses canonical glyph_history functions for tracking operator emissions.
+    Plasticity operators: OZ (Dissonance), THOL (Self-organization),
+    ZHIR (Mutation) - these represent structural flexibility.
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr, run_sequence
+    >>> from tnfr.operators.definitions import Dissonance, SelfOrganization
+    >>> from tnfr.metrics.learning_metrics import compute_learning_plasticity
+    >>> G, node = create_nfr("learner", epi=0.3, vf=1.0)
+    >>> # Apply reorganization operators
+    >>> run_sequence(G, node, [Dissonance(), SelfOrganization()])
+    >>> plasticity = compute_learning_plasticity(G, node, window=10)
+    >>> plasticity > 0.0  # Should show some plasticity
+    True
+    """
+    # Get glyph history directly from node
+    history = G.nodes[node].get("glyph_history", [])
+    if not history:
+        return 0.0
+
+    # Convert deque to list if needed
+    if hasattr(history, "__iter__"):
+        history = list(history)
+    else:
+        return 0.0
+
+    # Limit to window size
+    if window > 0 and len(history) > window:
+        history = history[-window:]
+
+    # Convert glyphs to operator names using canonical function
+    operator_names = glyph_history_to_operator_names(history)
+
+    # Count plastic operators: those that enable reorganization
+    plastic_ops = {DISSONANCE, SELF_ORGANIZATION, MUTATION}
+    plastic_count = sum(1 for op_name in operator_names if op_name in plastic_ops)
+
+    # Normalize by history length
+    return plastic_count / max(len(operator_names), 1)
+
+
+def compute_consolidation_index(
+    G: TNFRGraph,
+    node: Any,
+    window: int = 10,
+) -> float:
+    """Measure structural stabilization after learning (consolidation).
+
+    High consolidation indicates that learning has been stabilized and
+    integrated. Consolidation is measured by the frequency of stabilization
+    operators (IL, SHA) in the recent glyph history.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph storing TNFR nodes and their structural operator history.
+    node : Any
+        Node identifier within G.
+    window : int, default=10
+        Number of recent glyphs to analyze.
+
+    Returns
+    -------
+    float
+        Consolidation index in range [0.0, 1.0] where higher values indicate
+        greater stabilization of learned patterns.
+
+    Notes
+    -----
+    Reuses canonical glyph_history functions for tracking operator emissions.
+    Consolidation operators: IL (Coherence), SHA (Silence) - these represent
+    structural stabilization.
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr, run_sequence
+    >>> from tnfr.operators.definitions import Coherence, Silence
+    >>> from tnfr.metrics.learning_metrics import compute_consolidation_index
+    >>> G, node = create_nfr("learner", epi=0.5, vf=1.0)
+    >>> # Apply consolidation operators
+    >>> run_sequence(G, node, [Coherence(), Silence()])
+    >>> consolidation = compute_consolidation_index(G, node, window=10)
+    >>> consolidation > 0.0  # Should show some consolidation
+    True
+    """
+    # Get glyph history directly from node
+    history = G.nodes[node].get("glyph_history", [])
+    if not history:
+        return 0.0
+
+    # Convert deque to list if needed
+    if hasattr(history, "__iter__"):
+        history = list(history)
+    else:
+        return 0.0
+
+    # Limit to window size
+    if window > 0 and len(history) > window:
+        history = history[-window:]
+
+    # Convert glyphs to operator names using canonical function
+    operator_names = glyph_history_to_operator_names(history)
+
+    # Count stable operators: those that consolidate structure
+    stable_ops = {COHERENCE, SILENCE, RECURSIVITY}
+    stable_count = sum(1 for op_name in operator_names if op_name in stable_ops)
+
+    # Normalize by history length
+    return stable_count / max(len(operator_names), 1)
+
+
+def compute_learning_efficiency(
+    G: TNFRGraph,
+    node: Any,
+) -> float:
+    """Measure learning efficiency (EPI change per operator applied).
+
+    Efficiency represents how much structural change (ΔEPI) occurs per
+    operator application, indicating effective learning without excessive
+    reorganization.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph storing TNFR nodes and their structural state.
+    node : Any
+        Node identifier within G.
+
+    Returns
+    -------
+    float
+        Learning efficiency as ΔEPI / number_of_operators. Higher values
+        indicate more efficient learning (more change with fewer operations).
+
+    Notes
+    -----
+    Reuses canonical alias functions (get_attr) for accessing node attributes.
+    Requires node to have 'epi_initial' attribute set at creation time to
+    measure total EPI change.
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr, run_sequence
+    >>> from tnfr.operators.definitions import Emission, Reception
+    >>> from tnfr.metrics.learning_metrics import compute_learning_efficiency
+    >>> G, node = create_nfr("learner", epi=0.2, vf=1.0)
+    >>> G.nodes[node]["epi_initial"] = 0.2  # Track initial state
+    >>> # Apply learning operators
+    >>> run_sequence(G, node, [Emission(), Reception()])
+    >>> efficiency = compute_learning_efficiency(G, node)
+    >>> efficiency >= 0.0  # Should be non-negative
+    True
+    """
+    # Get current EPI using canonical get_attr
+    epi_current = float(get_attr(G.nodes[node], ALIAS_EPI, 0.0))
+
+    # Get initial EPI (should be set at node creation)
+    epi_initial = G.nodes[node].get("epi_initial", 0.0)
+
+    # Get number of operators applied from glyph history
+    history = G.nodes[node].get("glyph_history", [])
+    num_ops = len(history) if history else 0
+
+    if num_ops == 0:
+        return 0.0
+
+    # Calculate efficiency: total EPI change per operator
+    delta_epi = abs(epi_current - epi_initial)
+    return delta_epi / num_ops

tnfr/metrics/learning_metrics.pyi

@@ -0,0 +1,21 @@
+"""Type stubs for learning metrics module."""
+
+from typing import Any, Sequence
+
+from ..types import TNFRGraph
+
+def glyph_history_to_operator_names(glyph_history: Sequence[str]) -> list[str]: ...
+def compute_learning_plasticity(
+    G: TNFRGraph,
+    node: Any,
+    window: int = ...,
+) -> float: ...
+def compute_consolidation_index(
+    G: TNFRGraph,
+    node: Any,
+    window: int = ...,
+) -> float: ...
+def compute_learning_efficiency(
+    G: TNFRGraph,
+    node: Any,
+) -> float: ...

tnfr/metrics/phase_coherence.py

@@ -0,0 +1,351 @@
+"""Phase coherence metrics for TNFR networks.
+
+This module provides phase alignment and synchronization metrics based on
+circular statistics and the Kuramoto order parameter. These metrics are
+essential for measuring the effectiveness of the IL (Coherence) operator's
+phase locking mechanism.
+
+Mathematical Foundation
+-----------------------
+
+**Kuramoto Order Parameter:**
+
+The phase alignment quality is measured using the Kuramoto order parameter r:
+
+.. math::
+    r = |\\frac{1}{N} \\sum_{j=1}^{N} e^{i\\theta_j}|
+
+where:
+- r ∈ [0, 1]
+- r = 1: Perfect phase synchrony (all nodes aligned)
+- r = 0: Complete phase disorder (uniformly distributed phases)
+- θ_j: Phase of node j in radians
+
+**Circular Mean:**
+
+The mean phase of a set of angles is computed using the circular mean to
+properly handle phase wrap-around at 2π:
+
+.. math::
+    \\theta_{mean} = \\text{arg}\\left(\\frac{1}{N} \\sum_{j=1}^{N} e^{i\\theta_j}\\right)
+
+This ensures that phases near 0 and 2π are correctly averaged (e.g., 0.1 and
+6.2 radians average to near 0, not π).
+
+TNFR Context
+------------
+
+Phase alignment is a key component of the IL (Coherence) operator:
+
+- **IL Phase Locking**: θ_node → θ_node + α * (θ_network - θ_node)
+- **Network Synchrony**: High r indicates effective IL application
+- **Local vs. Global**: Phase alignment can be measured at node or network level
+- **Structural Traceability**: Phase metrics enable telemetry of synchronization
+
+Examples
+--------
+
+**Compute phase alignment for a node:**
+
+>>> import networkx as nx
+>>> from tnfr.metrics.phase_coherence import compute_phase_alignment
+>>> from tnfr.constants import THETA_PRIMARY
+>>> G = nx.Graph()
+>>> G.add_edges_from([(1, 2), (2, 3)])
+>>> G.nodes[1][THETA_PRIMARY] = 0.0
+>>> G.nodes[2][THETA_PRIMARY] = 0.1
+>>> G.nodes[3][THETA_PRIMARY] = 0.2
+>>> alignment = compute_phase_alignment(G, 2, radius=1)
+>>> 0.0 <= alignment <= 1.0
+True
+
+**Compute global phase coherence:**
+
+>>> from tnfr.metrics.phase_coherence import compute_global_phase_coherence
+>>> coherence = compute_global_phase_coherence(G)
+>>> 0.0 <= coherence <= 1.0
+True
+
+See Also
+--------
+
+operators.definitions.Coherence : IL operator that applies phase locking
+metrics.coherence.compute_global_coherence : Global structural coherence C(t)
+observers.kuramoto_order : Alternative Kuramoto order parameter implementation
+"""
+
+from __future__ import annotations
+
+import cmath
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph, NodeId
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_THETA
+from ..utils import get_numpy
+
+__all__ = [
+    "compute_phase_alignment",
+    "compute_global_phase_coherence",
+]
+
+
+def compute_phase_alignment(G: TNFRGraph, node: Any, radius: int = 1) -> float:
+    """Compute phase alignment quality for node and neighborhood.
+
+    Uses Kuramoto order parameter r = |⟨e^(iθ)⟩| to measure phase synchrony
+    within a node's neighborhood. Higher values indicate better phase alignment,
+    which is the goal of IL (Coherence) phase locking.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Network graph with node phase attributes (θ)
+    node : Any
+        Central node for local phase alignment computation
+    radius : int, default=1
+        Neighborhood radius:
+        - 1 = node + immediate neighbors (default)
+        - 2 = node + neighbors + neighbors-of-neighbors
+        - etc.
+
+    Returns
+    -------
+    float
+        Phase alignment in [0, 1] where:
+        - 1.0 = Perfect phase synchrony (all phases aligned)
+        - 0.0 = Complete phase disorder (uniformly distributed)
+
+    Notes
+    -----
+    **Mathematical Foundation:**
+
+    Kuramoto order parameter for local neighborhood:
+
+    .. math::
+        r = |\\frac{1}{N} \\sum_{j \\in \\mathcal{N}(i)} e^{i\\theta_j}|
+
+    where 𝒩(i) is the set of neighbors within `radius` of node i (including i).
+
+    **Use Cases:**
+
+    - **IL Effectiveness**: Measure phase locking success after IL application
+    - **Synchrony Monitoring**: Track local phase coherence over time
+    - **Hotspot Detection**: Identify regions with poor phase alignment
+    - **Coupling Validation**: Verify phase prerequisites before UM (Coupling)
+
+    **Special Cases:**
+
+    - Isolated node (no neighbors): Returns 1.0 (trivially synchronized)
+    - Single neighbor: Returns 1.0 (two nodes always "aligned")
+    - Empty neighborhood: Returns 1.0 (no disorder by definition)
+
+    **TNFR Context:**
+
+    Phase alignment is a precondition for effective coupling (UM operator) and
+    resonance (RA operator). The IL operator increases phase alignment through
+    its phase locking mechanism: θ_node → θ_node + α * (θ_network - θ_node).
+
+    See Also
+    --------
+    compute_global_phase_coherence : Network-wide phase coherence
+    operators.definitions.Coherence : IL operator with phase locking
+
+    Examples
+    --------
+    >>> import networkx as nx
+    >>> from tnfr.metrics.phase_coherence import compute_phase_alignment
+    >>> from tnfr.constants import THETA_PRIMARY
+    >>> G = nx.Graph()
+    >>> G.add_edges_from([(1, 2), (2, 3), (3, 4)])
+    >>> # Highly aligned phases
+    >>> for n in [1, 2, 3, 4]:
+    ...     G.nodes[n][THETA_PRIMARY] = 0.1 * n  # Small differences
+    >>> r = compute_phase_alignment(G, node=2, radius=1)
+    >>> r > 0.9  # Should be highly aligned
+    True
+    >>> # Disordered phases
+    >>> import numpy as np
+    >>> for n in [1, 2, 3, 4]:
+    ...     G.nodes[n][THETA_PRIMARY] = np.random.uniform(0, 2*np.pi)
+    >>> r = compute_phase_alignment(G, node=2, radius=1)
+    >>> 0.0 <= r <= 1.0  # Could be anywhere in range
+    True
+    """
+    import networkx as nx
+
+    # Get neighborhood
+    if radius == 1:
+        neighbors = set(G.neighbors(node)) | {node}
+    else:
+        try:
+            neighbors = set(
+                nx.single_source_shortest_path_length(G, node, cutoff=radius).keys()
+            )
+        except (nx.NetworkXError, KeyError):
+            # Node not in graph or graph is empty
+            neighbors = {node} if node in G.nodes else set()
+
+    # Collect phases from neighborhood
+    phases = []
+    for n in neighbors:
+        try:
+            theta = float(get_attr(G.nodes[n], ALIAS_THETA, 0.0))
+            phases.append(theta)
+        except (KeyError, ValueError, TypeError):
+            # Skip nodes with invalid phase data
+            continue
+
+    # Handle edge cases
+    if not phases:
+        return 1.0  # Empty neighborhood: trivially synchronized
+
+    if len(phases) == 1:
+        return 1.0  # Single node: perfect synchrony
+
+    # Compute Kuramoto order parameter using circular statistics
+    np = get_numpy()
+
+    if np is not None:
+        # NumPy vectorized computation
+        phases_array = np.array(phases)
+        complex_phases = np.exp(1j * phases_array)
+        mean_complex = np.mean(complex_phases)
+        r = np.abs(mean_complex)
+        return float(r)
+    else:
+        # Pure Python fallback
+
+        # Convert phases to complex exponentials
+        complex_phases = [cmath.exp(1j * theta) for theta in phases]
+
+        # Compute mean complex phasor
+        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)
+
+        # Kuramoto order parameter is magnitude of mean phasor
+        r = abs(mean_complex)
+        return float(r)
+
+
+def compute_global_phase_coherence(G: TNFRGraph) -> float:
+    """Compute global phase coherence across entire network.
+
+    Measures network-wide phase synchronization using the Kuramoto order
+    parameter applied to all nodes. This is the global analog of
+    compute_phase_alignment and indicates overall phase alignment quality.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Network graph with node phase attributes (θ)
+
+    Returns
+    -------
+    float
+        Global phase coherence in [0, 1] where:
+        - 1.0 = Perfect network-wide phase synchrony
+        - 0.0 = Complete phase disorder across network
+
+    Notes
+    -----
+    **Mathematical Foundation:**
+
+    Global Kuramoto order parameter:
+
+    .. math::
+        r_{global} = |\\frac{1}{N} \\sum_{j=1}^{N} e^{i\\theta_j}|
+
+    where N is the total number of nodes in the network.
+
+    **Use Cases:**
+
+    - **IL Effectiveness**: Measure global impact of IL phase locking
+    - **Network Health**: Monitor overall synchronization state
+    - **Convergence Tracking**: Verify phase alignment over time
+    - **Bifurcation Detection**: Low r_global may indicate impending split
+
+    **Special Cases:**
+
+    - Empty network: Returns 1.0 (no disorder by definition)
+    - Single node: Returns 1.0 (trivially synchronized)
+    - All phases = 0: Returns 1.0 (perfect alignment)
+
+    **TNFR Context:**
+
+    Global phase coherence is a key metric for network structural health.
+    Repeated IL application should increase r_global as nodes synchronize
+    their phases. Combined with C(t) (structural coherence), r_global provides
+    a complete picture of network stability.
+
+    See Also
+    --------
+    compute_phase_alignment : Local phase alignment for node neighborhoods
+    metrics.coherence.compute_global_coherence : Global structural coherence C(t)
+    observers.kuramoto_order : Alternative Kuramoto implementation
+
+    Examples
+    --------
+    >>> import networkx as nx
+    >>> from tnfr.metrics.phase_coherence import compute_global_phase_coherence
+    >>> from tnfr.constants import THETA_PRIMARY
+    >>> G = nx.Graph()
+    >>> G.add_nodes_from([1, 2, 3, 4])
+    >>> # Aligned network
+    >>> for n in [1, 2, 3, 4]:
+    ...     G.nodes[n][THETA_PRIMARY] = 0.5  # All same phase
+    >>> r = compute_global_phase_coherence(G)
+    >>> r == 1.0  # Perfect alignment
+    True
+    >>> # Disordered network
+    >>> import numpy as np
+    >>> for n in [1, 2, 3, 4]:
+    ...     G.nodes[n][THETA_PRIMARY] = np.random.uniform(0, 2*np.pi)
+    >>> r = compute_global_phase_coherence(G)
+    >>> 0.0 <= r <= 1.0
+    True
+    """
+    # Collect all node phases
+    phases = []
+    for n in G.nodes():
+        try:
+            theta = float(get_attr(G.nodes[n], ALIAS_THETA, 0.0))
+            phases.append(theta)
+        except (KeyError, ValueError, TypeError):
+            # Skip nodes with invalid phase data
+            continue
+
+    # Handle edge cases
+    if not phases:
+        return 1.0  # Empty network: trivially synchronized
+
+    if len(phases) == 1:
+        return 1.0  # Single node: perfect synchrony
+
+    # Compute Kuramoto order parameter using circular statistics
+    np = get_numpy()
+
+    if np is not None:
+        # NumPy vectorized computation
+        phases_array = np.array(phases)
+        complex_phases = np.exp(1j * phases_array)
+        mean_complex = np.mean(complex_phases)
+        r = np.abs(mean_complex)
+        return float(r)
+    else:
+        # Pure Python fallback
+
+        # Convert phases to complex exponentials
+        complex_phases = [cmath.exp(1j * theta) for theta in phases]
+
+        # Compute mean complex phasor
+        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)
+
+        # Kuramoto order parameter is magnitude of mean phasor
+        r = abs(mean_complex)
+        return float(r)