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

tnfr/metrics/phase_compatibility.py

@@ -0,0 +1,349 @@
+"""Unified phase compatibility calculations for TNFR operators.
+
+This module provides canonical implementations of phase-based coupling strength
+calculations used by multiple TNFR operators (UM, RA, THOL). All operators that
+perform phase-based coupling or propagation MUST use these functions to ensure
+consistency with TNFR physics and Invariant #5.
+
+Physical Foundation
+-------------------
+
+**Phase Compatibility in TNFR:**
+
+Coupling between nodes requires phase synchronization. Destructive interference
+occurs when phases are misaligned (antiphase), while constructive interference
+occurs when phases align. The coupling strength formula reflects this physics:
+
+.. math::
+    \\text{coupling_strength} = 1.0 - \\frac{|\\Delta\\phi|}{\\pi}
+
+where Δφ is the phase difference in radians.
+
+**Physical Interpretation:**
+
+- Δφ = 0 (perfect alignment) → coupling = 1.0 (maximum constructive interference)
+- Δφ = π/2 (orthogonal) → coupling = 0.5 (partial coupling)
+- Δφ = π (antiphase) → coupling = 0.0 (destructive interference)
+
+**TNFR Invariant #5:** "No coupling without explicit phase verification"
+(see AGENTS.md). All coupling operations must verify phase compatibility
+before propagating structural information.
+
+Canonical Usage
+---------------
+
+**Operators Using This Module:**
+
+1. **UM (Coupling)**: Phase synchronization and network formation
+2. **RA (Resonance)**: Coherence propagation through phase-aligned paths
+3. **THOL (Self-organization)**: Sub-EPI propagation to coupled neighbors
+
+**Before Refactoring:**
+
+Each operator implemented its own phase compatibility calculation, leading
+to potential inconsistencies and maintenance burden.
+
+**After Refactoring:**
+
+All operators use the canonical functions defined here, ensuring theoretical
+consistency and simplifying validation against TNFR physics.
+
+Examples
+--------
+
+**Basic coupling strength calculation:**
+
+>>> import math
+>>> # Perfect alignment
+>>> compute_phase_coupling_strength(0.0, 0.0)
+1.0
+>>> # Orthogonal phases
+>>> compute_phase_coupling_strength(0.0, math.pi/2)
+0.5
+>>> # Antiphase (destructive)
+>>> round(compute_phase_coupling_strength(0.0, math.pi), 10)
+0.0
+
+**Phase compatibility check:**
+
+>>> # Check if phases are compatible for coupling
+>>> is_phase_compatible(0.0, 0.1, threshold=0.5)
+True
+>>> is_phase_compatible(0.0, math.pi, threshold=0.5)
+False
+
+**Network phase alignment:**
+
+>>> import networkx as nx
+>>> from tnfr.constants.aliases import ALIAS_THETA
+>>> G = nx.Graph()
+>>> G.add_edges_from([(0, 1), (1, 2)])
+>>> for i, theta in enumerate([0.0, 0.1, 0.2]):
+...     G.nodes[i][ALIAS_THETA] = theta
+>>> alignment = compute_network_phase_alignment(G, node=1, radius=1)
+>>> 0.0 <= alignment <= 1.0
+True
+
+See Also
+--------
+
+operators.definitions : Operator implementations (UM, RA, THOL)
+metrics.phase_coherence : Kuramoto order parameter and phase metrics
+AGENTS.md : Invariant #5 - Phase Verification requirement
+UNIFIED_GRAMMAR_RULES.md : U3 - RESONANT COUPLING grammar rule
+
+References
+----------
+
+.. [1] TNFR.pdf § 2.3: Phase synchronization and coupling
+.. [2] AGENTS.md: Invariant #5 - No coupling without phase verification
+.. [3] UNIFIED_GRAMMAR_RULES.md: U3 - Resonant Coupling requires |φᵢ - φⱼ| ≤ Δφ_max
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph, NodeId
+
+from ..utils.numeric import angle_diff
+
+__all__ = [
+    "compute_phase_coupling_strength",
+    "is_phase_compatible",
+    "compute_network_phase_alignment",
+]
+
+
+def compute_phase_coupling_strength(
+    theta_a: float,
+    theta_b: float,
+) -> float:
+    """Compute canonical coupling strength from phase difference.
+
+    This is the canonical TNFR formula for phase-based coupling strength,
+    representing the degree of constructive vs. destructive interference
+    between two oscillating nodes.
+
+    Parameters
+    ----------
+    theta_a : float
+        Phase of first node in radians [0, 2π)
+    theta_b : float
+        Phase of second node in radians [0, 2π)
+
+    Returns
+    -------
+    float
+        Coupling strength in [0, 1]:
+        - 1.0: Perfect phase alignment (Δφ = 0)
+        - 0.5: Orthogonal phases (Δφ = π/2)
+        - 0.0: Antiphase (Δφ = π, destructive interference)
+
+    Notes
+    -----
+    **Formula:**
+
+    .. math::
+        \\text{coupling_strength} = 1.0 - \\frac{|\\text{angle_diff}(\\theta_b, \\theta_a)|}{\\pi}
+
+    The formula uses :func:`~tnfr.utils.numeric.angle_diff` to compute the
+    shortest angular distance between phases, properly handling wrap-around
+    at 2π boundaries.
+
+    **Physics:**
+
+    - Based on wave interference physics: aligned phases → constructive interference
+    - Antiphase (Δφ = π) → destructive interference → zero coupling
+    - Linear interpolation between extremes reflects gradual transition
+
+    **Used By:**
+
+    - UM (Coupling): For determining link formation and synchronization strength
+    - RA (Resonance): For gating coherence propagation to neighbors
+    - THOL (Self-organization): For sub-EPI propagation through coupled nodes
+
+    **Invariant #5:** This function implements the explicit phase verification
+    required by TNFR Invariant #5 (AGENTS.md). All coupling operations must
+    verify phase compatibility before propagating structural information.
+
+    Examples
+    --------
+    >>> import math
+    >>> # Perfect alignment
+    >>> compute_phase_coupling_strength(0.0, 0.0)
+    1.0
+    >>> # Small misalignment
+    >>> compute_phase_coupling_strength(0.0, 0.1)  # doctest: +ELLIPSIS
+    0.96...
+    >>> # Orthogonal phases
+    >>> compute_phase_coupling_strength(0.0, math.pi/2)
+    0.5
+    >>> # Antiphase (destructive)
+    >>> round(compute_phase_coupling_strength(0.0, math.pi), 10)
+    0.0
+    >>> # Wrap-around handling
+    >>> compute_phase_coupling_strength(0.1, 2*math.pi - 0.1)  # doctest: +ELLIPSIS
+    0.93...
+
+    See Also
+    --------
+    is_phase_compatible : Boolean compatibility check with threshold
+    angle_diff : Shortest angular distance between phases
+    """
+    phase_diff = abs(angle_diff(theta_b, theta_a))
+    return 1.0 - (phase_diff / math.pi)
+
+
+def is_phase_compatible(
+    theta_a: float,
+    theta_b: float,
+    threshold: float = 0.5,
+) -> bool:
+    """Check if two phases are compatible for coupling/propagation.
+
+    Determines whether two nodes are sufficiently phase-aligned to support
+    resonant coupling, based on a configurable coupling strength threshold.
+
+    Parameters
+    ----------
+    theta_a : float
+        Phase of first node in radians [0, 2π)
+    theta_b : float
+        Phase of second node in radians [0, 2π)
+    threshold : float, default=0.5
+        Minimum coupling strength required for compatibility [0, 1].
+        Default 0.5 corresponds to maximum phase difference of π/2 (orthogonal).
+
+    Returns
+    -------
+    bool
+        True if coupling_strength >= threshold (nodes are compatible)
+        False if coupling_strength < threshold (nodes are incompatible)
+
+    Notes
+    -----
+    **Common Thresholds:**
+
+    - 0.5 (default): Allows coupling up to π/2 phase difference
+    - 0.7: More restrictive, requires Δφ < π/2.1 (~95°)
+    - 0.9: Very restrictive, requires Δφ < π/10 (~18°)
+
+    **Usage:**
+
+    - **UM (Coupling)**: Gate link formation based on phase compatibility
+    - **RA (Resonance)**: Filter neighbors for coherence propagation
+    - **THOL propagation**: Minimum coupling for sub-EPI propagation
+
+    **Invariant #5:** This function provides a boolean interface to the
+    phase verification requirement (AGENTS.md Invariant #5).
+
+    Examples
+    --------
+    >>> import math
+    >>> # In-phase: compatible
+    >>> is_phase_compatible(0.0, 0.1, threshold=0.5)
+    True
+    >>> # Orthogonal: at threshold boundary
+    >>> is_phase_compatible(0.0, math.pi/2, threshold=0.5)
+    True
+    >>> # Slightly beyond orthogonal: incompatible
+    >>> is_phase_compatible(0.0, math.pi/2 + 0.1, threshold=0.5)
+    False
+    >>> # Antiphase: incompatible
+    >>> is_phase_compatible(0.0, math.pi, threshold=0.5)
+    False
+    >>> # Higher threshold: more restrictive
+    >>> is_phase_compatible(0.0, math.pi/4, threshold=0.9)
+    False
+    >>> is_phase_compatible(0.0, 0.1, threshold=0.9)
+    True
+
+    See Also
+    --------
+    compute_phase_coupling_strength : Continuous coupling strength [0, 1]
+    """
+    coupling = compute_phase_coupling_strength(theta_a, theta_b)
+    return coupling >= threshold
+
+
+def compute_network_phase_alignment(
+    G: TNFRGraph,
+    node: NodeId,
+    radius: int = 1,
+) -> float:
+    """Compute phase alignment in local neighborhood using Kuramoto order parameter.
+
+    This is a convenience wrapper around the existing
+    :func:`~tnfr.metrics.phase_coherence.compute_phase_alignment` function,
+    provided for API consistency within this module.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        TNFR network graph containing nodes with phase (theta) attributes
+    node : NodeId
+        Central node for neighborhood analysis
+    radius : int, default=1
+        Neighborhood radius in hops from central node
+
+    Returns
+    -------
+    float
+        Phase alignment quality in [0, 1]:
+        - 1.0: Perfect phase synchronization (all nodes aligned)
+        - 0.0: Complete phase disorder (random phases)
+
+    Notes
+    -----
+    **Kuramoto Order Parameter:**
+
+    Measures collective phase synchrony using:
+
+    .. math::
+        r = |\\frac{1}{N} \\sum_{j=1}^{N} e^{i\\theta_j}|
+
+    **Used By:**
+
+    - **RA (Resonance)**: Assess network coherence for propagation gating
+    - **IL (Coherence)**: Validate phase locking effectiveness
+
+    **Implementation:**
+
+    This function delegates to the existing implementation in
+    :mod:`tnfr.metrics.phase_coherence` to avoid code duplication
+    while providing a unified API for phase compatibility calculations.
+
+    Examples
+    --------
+    >>> import networkx as nx
+    >>> from tnfr.constants.aliases import ALIAS_THETA
+    >>> G = nx.Graph()
+    >>> G.add_edges_from([(0, 1), (1, 2), (2, 3)])
+    >>> # Highly aligned phases
+    >>> for i in range(4):
+    ...     G.nodes[i][ALIAS_THETA] = i * 0.1
+    >>> alignment = compute_network_phase_alignment(G, node=1, radius=1)
+    >>> alignment > 0.9  # High alignment
+    True
+    >>> # Random phases
+    >>> import math
+    >>> G.nodes[0][ALIAS_THETA] = 0.0
+    >>> G.nodes[1][ALIAS_THETA] = math.pi/3
+    >>> G.nodes[2][ALIAS_THETA] = 2*math.pi/3
+    >>> G.nodes[3][ALIAS_THETA] = math.pi
+    >>> alignment = compute_network_phase_alignment(G, node=1, radius=1)
+    >>> 0.0 <= alignment <= 1.0
+    True
+
+    See Also
+    --------
+    metrics.phase_coherence.compute_phase_alignment : Underlying implementation
+    metrics.phase_coherence.compute_global_phase_coherence : Global network metric
+    """
+    # Import existing function to avoid duplication
+    from .phase_coherence import compute_phase_alignment
+
+    return compute_phase_alignment(G, node, radius=radius)

tnfr/metrics/reporting.py

@@ -0,0 +1,183 @@
+"""Reporting helpers for collected metrics."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from heapq import nlargest
+from statistics import StatisticsError, fmean, mean
+from typing import Any
+
+from ..glyph_history import ensure_history
+from ..sense import sigma_rose
+from ..types import NodeId, TNFRGraph
+from .glyph_timing import for_each_glyph
+
+__all__ = [
+    "Tg_global",
+    "Tg_by_node",
+    "latency_series",
+    "glyphogram_series",
+    "glyph_top",
+    "build_metrics_summary",
+]
+
+# ---------------------------------------------------------------------------
+# Reporting functions
+# ---------------------------------------------------------------------------
+
+
+def Tg_global(G: TNFRGraph, normalize: bool = True) -> dict[str, float]:
+    """Total glyph dwell time per class."""
+
+    hist = ensure_history(G)
+    tg_total: dict[str, float] = hist.get("Tg_total", {})
+    total = sum(tg_total.values()) or 1.0
+    out: dict[str, float] = {}
+
+    def add(g: str) -> None:
+        val = float(tg_total.get(g, 0.0))
+        out[g] = val / total if normalize else val
+
+    for_each_glyph(add)
+    return out
+
+
+def Tg_by_node(
+    G: TNFRGraph, n: NodeId, normalize: bool = False
+) -> dict[str, float] | dict[str, list[float]]:
+    """Per-node glyph dwell summary."""
+
+    hist = ensure_history(G)
+    rec = hist.get("Tg_by_node", {}).get(n, {})
+    if not normalize:
+        runs_out: dict[str, list[float]] = {}
+
+        def copy_runs(g: str) -> None:
+            runs_out[g] = list(rec.get(g, []))
+
+        for_each_glyph(copy_runs)
+        return runs_out
+    mean_out: dict[str, float] = {}
+
+    def add(g: str) -> None:
+        runs = rec.get(g, [])
+        mean_out[g] = float(mean(runs)) if runs else 0.0
+
+    for_each_glyph(add)
+    return mean_out
+
+
+def latency_series(G: TNFRGraph) -> dict[str, list[float]]:
+    """Return latency samples as ``{"t": [...], "value": [...]}``."""
+
+    hist = ensure_history(G)
+    xs = hist.get("latency_index", [])
+    return {
+        "t": [float(x.get("t", i)) for i, x in enumerate(xs)],
+        "value": [float(x.get("value", 0.0)) for x in xs],
+    }
+
+
+def glyphogram_series(G: TNFRGraph) -> dict[str, list[float]]:
+    """Return glyphogram time series keyed by glyph label."""
+
+    hist = ensure_history(G)
+    xs = hist.get("glyphogram", [])
+    if not xs:
+        return {"t": []}
+    out: dict[str, list[float]] = {
+        "t": [float(x.get("t", i)) for i, x in enumerate(xs)]
+    }
+
+    def add(g: str) -> None:
+        out[g] = [float(x.get(g, 0.0)) for x in xs]
+
+    for_each_glyph(add)
+    return out
+
+
+def glyph_top(G: TNFRGraph, k: int = 3) -> list[tuple[str, float]]:
+    """Top-k structural operators by ``Tg_global`` fraction."""
+
+    k = int(k)
+    if k <= 0:
+        raise ValueError("k must be a positive integer")
+    tg = Tg_global(G, normalize=True)
+    return nlargest(k, tg.items(), key=lambda kv: kv[1])
+
+
+def build_metrics_summary(
+    G: TNFRGraph, *, series_limit: int | None = None
+) -> tuple[
+    dict[str, float | dict[str, float] | dict[str, list[float]] | dict[str, int]], bool
+]:
+    """Collect a compact metrics summary for CLI reporting.
+
+    This factory aggregates various TNFR metrics into a unified summary
+    structure suitable for command-line display and analysis. It combines
+    glyph timing statistics, latency measurements, and coherence indicators.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the recorded metrics history.
+    series_limit : int | None, optional
+        Maximum number of samples to keep for each glyphogram series.
+        When ``None`` or non-positive, returns the full history without
+        trimming. Default is None.
+
+    Returns
+    -------
+    tuple[dict, bool]
+        A two-element tuple containing:
+
+        - **summary** (dict): Metrics dictionary with the following keys:
+
+          - ``Tg_global``: Normalized glyph dwell time per class
+          - ``latency_mean``: Mean latency across all samples
+          - ``rose``: Sigma rose coherence indicator
+          - ``glyphogram``: Time series of glyph activity (trimmed if limit set)
+
+        - **has_data** (bool): True if latency data is available, False otherwise
+
+    Notes
+    -----
+    The series trimming feature is useful for limiting memory usage when
+    tracking long-running simulations. Trimming only affects the glyphogram
+    time series; aggregate statistics remain computed from the full history.
+    """
+
+    tg = Tg_global(G, normalize=True)
+    latency = latency_series(G)
+    glyph = glyphogram_series(G)
+    rose = sigma_rose(G)
+
+    latency_values = latency.get("value", [])
+    try:
+        latency_mean = fmean(latency_values)
+    except StatisticsError:
+        latency_mean = 0.0
+
+    limit: int | None
+    if series_limit is None:
+        limit = None
+    else:
+        limit = int(series_limit)
+        if limit <= 0:
+            limit = None
+
+    def _trim(values: Sequence[Any]) -> list[Any]:
+        seq = list(values)
+        if limit is None:
+            return seq
+        return seq[:limit]
+
+    glyph_summary = {k: _trim(v) for k, v in glyph.items()}
+
+    summary = {
+        "Tg_global": tg,
+        "latency_mean": latency_mean,
+        "rose": rose,
+        "glyphogram": glyph_summary,
+    }
+    return summary, bool(latency_values)

tnfr/metrics/reporting.pyi

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from ..types import NodeId, TNFRGraph
+
+__all__ = [
+    "Tg_global",
+    "Tg_by_node",
+    "latency_series",
+    "glyphogram_series",
+    "glyph_top",
+    "build_metrics_summary",
+]
+
+def Tg_global(G: TNFRGraph, normalize: bool = True) -> dict[str, float]: ...
+def Tg_by_node(
+    G: TNFRGraph, n: NodeId, normalize: bool = False
+) -> dict[str, float] | dict[str, list[float]]: ...
+def latency_series(G: TNFRGraph) -> dict[str, list[float]]: ...
+def glyphogram_series(G: TNFRGraph) -> dict[str, list[float]]: ...
+def glyph_top(G: TNFRGraph, k: int = 3) -> list[tuple[str, float]]: ...
+def build_metrics_summary(
+    G: TNFRGraph, *, series_limit: int | None = None
+) -> tuple[
+    dict[str, float | dict[str, float] | dict[str, list[float]] | dict[str, int]], bool
+]: ...