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

tnfr/metrics/diagnosis.pyi

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ALIAS_DNFR: Any
+ALIAS_EPI: Any
+ALIAS_SI: Any
+ALIAS_VF: Any
+CallbackEvent: Any
+CoherenceMatrixPayload: Any
+Iterable: Any
+ProcessPoolExecutor: Any
+StatisticsError: Any
+TNFRGraph: Any
+TRANSITION: Any
+VF_KEY: Any
+append_metric: Any
+callback_manager: Any
+clamp01: Any
+coherence_matrix: Any
+compute_dnfr_accel_max: Any
+compute_theta_trig: Any
+dissonance_events: Any
+ensure_history: Any
+fmean: Any
+ge: Any
+get_aliases: Any
+get_attr: Any
+get_numpy: Any
+get_param: Any
+get_trig_cache: Any
+le: Any
+local_phase_sync: Any
+math: Any
+min_max_range: Any
+normalize_dnfr: Any
+partial: Any
+register_diagnosis_callbacks: Any
+similarity_abs: Any
+
+class RLocalWorkerArgs:
+    chunk: Sequence[Any]
+    coherence_nodes: Sequence[Any]
+    weight_matrix: Any
+    weight_index: Mapping[Any, int]
+    neighbors_map: Mapping[Any, tuple[Any, ...]]
+    cos_map: Mapping[Any, float]
+    sin_map: Mapping[Any, float]
+
+    def __init__(
+        self,
+        chunk: Sequence[Any],
+        coherence_nodes: Sequence[Any],
+        weight_matrix: Any,
+        weight_index: Mapping[Any, int],
+        neighbors_map: Mapping[Any, tuple[Any, ...]],
+        cos_map: Mapping[Any, float],
+        sin_map: Mapping[Any, float],
+    ) -> None: ...
+
+class NeighborMeanWorkerArgs:
+    chunk: Sequence[Any]
+    neighbors_map: Mapping[Any, tuple[Any, ...]]
+    epi_map: Mapping[Any, float]
+
+    def __init__(
+        self,
+        chunk: Sequence[Any],
+        neighbors_map: Mapping[Any, tuple[Any, ...]],
+        epi_map: Mapping[Any, float],
+    ) -> None: ...
+
+def _rlocal_worker(args: RLocalWorkerArgs) -> list[float]: ...
+def _neighbor_mean_worker(args: NeighborMeanWorkerArgs) -> list[float | None]: ...
+def _state_from_thresholds(
+    Rloc: float, dnfr_n: float, cfg: Mapping[str, Any]
+) -> str: ...
+def _recommendation(state: str, cfg: Mapping[str, Any]) -> list[Any]: ...
+def _get_last_weights(
+    G: TNFRGraph,
+    hist: Mapping[str, Sequence[CoherenceMatrixPayload | None]],
+) -> tuple[CoherenceMatrixPayload | None, CoherenceMatrixPayload | None]: ...

tnfr/metrics/emergence.py

@@ -0,0 +1,245 @@
+"""Emergence metrics for T'HOL structural metabolism.
+
+Provides quantitative measures of complexity emergence, bifurcation dynamics,
+and metabolic efficiency in self-organizing systems.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..types import NodeId, TNFRGraph
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_EPI
+
+__all__ = [
+    "compute_structural_complexity",
+    "compute_bifurcation_rate",
+    "compute_metabolic_efficiency",
+    "compute_emergence_index",
+]
+
+# Emergence index calculation constant
+_EMERGENCE_INDEX_EPSILON = 1e-6  # Small value to avoid zero in geometric mean
+
+
+def compute_structural_complexity(G: TNFRGraph, node: NodeId) -> int:
+    """Measure structural complexity by counting nested sub-EPIs.
+
+    Structural complexity reflects the number of bifurcations that have
+    occurred, indicating the degree of self-organized internal structure.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+
+    Returns
+    -------
+    int
+        Number of sub-EPIs generated through T'HOL bifurcations
+
+    Notes
+    -----
+    Higher complexity indicates more sophisticated internal organization
+    but may also indicate higher maintenance costs (higher νf required).
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.operators.definitions import SelfOrganization
+    >>> from tnfr.metrics.emergence import compute_structural_complexity
+    >>> G, node = create_nfr("system", epi=0.5, vf=1.0)
+    >>> # Initialize history for bifurcation
+    >>> G.nodes[node]["epi_history"] = [0.3, 0.4, 0.6]  # Accelerating
+    >>> SelfOrganization()(G, node, tau=0.05)  # Low threshold
+    >>> complexity = compute_structural_complexity(G, node)
+    >>> complexity  # doctest: +SKIP
+    1
+    """
+    sub_epis = G.nodes[node].get("sub_epis", [])
+    return len(sub_epis)
+
+
+def compute_bifurcation_rate(G: TNFRGraph, node: NodeId, window: int = 10) -> float:
+    """Calculate frequency of bifurcations in recent history.
+
+    Bifurcation rate indicates how actively the node is generating new
+    structural complexity through T'HOL operations.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+    window : int
+        Time window for rate calculation (in operator steps, default 10)
+
+    Returns
+    -------
+    float
+        Bifurcations per step in the window (0.0 to 1.0 typical)
+
+    Notes
+    -----
+    High bifurcation rate (> 0.5) may indicate:
+    - Active adaptation to changing environment
+    - High structural instability
+    - Rich exploratory dynamics
+
+    Low rate (< 0.1) may indicate:
+    - Stable structural regime
+    - Low adaptive pressure
+    - Insufficient ΔNFR for bifurcation
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.metrics.emergence import compute_bifurcation_rate
+    >>> G, node = create_nfr("evolving", epi=0.6, vf=1.0)
+    >>> # Simulate several bifurcations
+    >>> G.nodes[node]["sub_epis"] = [
+    ...     {"timestamp": 5}, {"timestamp": 8}, {"timestamp": 12}
+    ... ]
+    >>> rate = compute_bifurcation_rate(G, node, window=10)
+    >>> rate  # 2 bifurcations in last 10 steps
+    0.2
+    """
+    sub_epis = G.nodes[node].get("sub_epis", [])
+    if not sub_epis:
+        return 0.0
+
+    # Get current timestamp from glyph history
+    current_time = len(G.nodes[node].get("glyph_history", []))
+
+    # Count bifurcations in window
+    recent_bifurcations = [
+        s for s in sub_epis if s.get("timestamp", 0) >= (current_time - window)
+    ]
+
+    return len(recent_bifurcations) / float(window)
+
+
+def compute_metabolic_efficiency(G: TNFRGraph, node: NodeId) -> float:
+    """Calculate EPI gain per T'HOL application (metabolic efficiency).
+
+    Metabolic efficiency measures how effectively T'HOL converts
+    reorganization events into stable structural complexity (EPI growth).
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+
+    Returns
+    -------
+    float
+        Average EPI increase per T'HOL application
+        Returns 0.0 if no T'HOL applications recorded
+
+    Notes
+    -----
+    High efficiency (> 0.1) indicates:
+    - Effective self-organization
+    - Strong coherence maintenance
+    - Productive metabolic cycles
+
+    Low efficiency (< 0.01) indicates:
+    - Ineffective reorganization
+    - High structural friction
+    - Possible need for different operator sequences
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.metrics.emergence import compute_metabolic_efficiency
+    >>> G, node = create_nfr("productive", epi=0.5, vf=1.0)
+    >>> # Record initial EPI
+    >>> G.nodes[node]["epi_initial"] = 0.3
+    >>> # Simulate T'HOL applications
+    >>> G.nodes[node]["glyph_history"] = ["THOL", "THOL", "IL"]
+    >>> # Current EPI increased to 0.5
+    >>> efficiency = compute_metabolic_efficiency(G, node)
+    >>> efficiency  # (0.5 - 0.3) / 2 = 0.1
+    0.1
+    """
+    from ..types import Glyph
+
+    # Count T'HOL applications
+    glyph_history = G.nodes[node].get("glyph_history", [])
+    thol_count = sum(1 for g in glyph_history if g == "THOL" or g == Glyph.THOL.value)
+
+    if thol_count == 0:
+        return 0.0
+
+    # Calculate EPI delta
+    current_epi = float(get_attr(G.nodes[node], ALIAS_EPI, 0.0))
+    initial_epi = float(G.nodes[node].get("epi_initial", current_epi))
+
+    epi_gain = current_epi - initial_epi
+
+    return epi_gain / float(thol_count)
+
+
+def compute_emergence_index(G: TNFRGraph, node: NodeId) -> float:
+    """Composite metric combining complexity, rate, and efficiency.
+
+    Emergence index provides a holistic measure of T'HOL metabolic health,
+    combining structural complexity, bifurcation dynamics, and efficiency.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+
+    Returns
+    -------
+    float
+        Emergence index (0.0 to ~1.0 typical, higher indicates more emergent)
+        Computed as: sqrt(complexity * rate * efficiency)
+
+    Notes
+    -----
+    This index balances three factors:
+    - Complexity: how much structure has emerged
+    - Rate: how actively new structure forms
+    - Efficiency: how productive each reorganization is
+
+    High index (> 0.5) indicates healthy emergent dynamics.
+    Low index (< 0.1) suggests reorganization is stalled or inefficient.
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.metrics.emergence import compute_emergence_index
+    >>> G, node = create_nfr("emergent", epi=0.7, vf=1.0)
+    >>> # Setup for high emergence
+    >>> G.nodes[node]["epi_initial"] = 0.3
+    >>> G.nodes[node]["glyph_history"] = ["THOL", "THOL", "IL"]
+    >>> G.nodes[node]["sub_epis"] = [{"timestamp": 1}, {"timestamp": 2}]
+    >>> index = compute_emergence_index(G, node)
+    >>> index  # doctest: +SKIP
+    0.63...
+    """
+    complexity = float(compute_structural_complexity(G, node))
+    rate = compute_bifurcation_rate(G, node)
+    efficiency = compute_metabolic_efficiency(G, node)
+
+    # Geometric mean to avoid dominance by any single factor
+    # Add epsilon to avoid zero multiplication when no bifurcations occurred
+    index = (
+        (complexity + _EMERGENCE_INDEX_EPSILON)
+        * (rate + _EMERGENCE_INDEX_EPSILON)
+        * (efficiency + _EMERGENCE_INDEX_EPSILON)
+    ) ** (1.0 / 3.0)
+
+    return index

tnfr/metrics/export.py

@@ -0,0 +1,179 @@
+"""Metrics export."""
+
+from __future__ import annotations
+
+import csv
+import math
+from collections.abc import Iterable, Iterator, Sequence
+from itertools import tee, zip_longest
+from typing import Mapping, TextIO
+
+from ..config.constants import GLYPHS_CANONICAL
+from ..glyph_history import ensure_history
+from ..utils import json_dumps, safe_write
+from ..types import Graph, SigmaTrace
+from .core import glyphogram_series
+
+
+def _write_csv(
+    path: str,
+    headers: Sequence[str],
+    rows: Iterable[Sequence[object]],
+    *,
+    output_dir: str | None = None,
+) -> None:
+    def _write(f: TextIO) -> None:
+        writer = csv.writer(f)
+        writer.writerow(headers)
+        for row in rows:
+            writer.writerow(row)
+
+    safe_write(path, _write, newline="", base_dir=output_dir)
+
+
+def _iter_glif_rows(
+    glyph: Mapping[str, Sequence[float]],
+) -> Iterator[list[float]]:
+    ts = glyph.get("t", [])
+    # Precompute columns for each glyph to avoid repeated lookups.
+    # ``default_col`` is shared by reference for missing glyphs to prevent
+    # unnecessary list allocations.
+    default_col = [0] * len(ts)
+    cols = [glyph.get(g, default_col) for g in GLYPHS_CANONICAL]
+    for i, t in enumerate(ts):
+        yield [t] + [col[i] for col in cols]
+
+
+def export_metrics(
+    G: Graph,
+    base_path: str,
+    fmt: str = "csv",
+    *,
+    output_dir: str | None = None,
+) -> None:
+    """Dump glyphogram and σ(t) trace to compact CSV or JSON files.
+
+    Parameters
+    ----------
+    G : Graph
+        The TNFR graph containing metrics to export.
+    base_path : str
+        Base filename for exported files (without extension).
+    fmt : str, default='csv'
+        Export format: 'csv' or 'json'.
+    output_dir : str | None, optional
+        Output directory to restrict exports. If provided, all exports
+        must stay within this directory (prevents path traversal).
+
+    Raises
+    ------
+    ValueError
+        If the path is invalid or format is unsupported.
+    PathTraversalError
+        If path traversal is detected when output_dir is provided.
+    """
+    from pathlib import Path
+
+    hist = ensure_history(G)
+    glyph = glyphogram_series(G)
+    sigma_x = hist.get("sense_sigma_x", [])
+    sigma_y = hist.get("sense_sigma_y", [])
+    sigma_mag = hist.get("sense_sigma_mag", [])
+    sigma_angle = hist.get("sense_sigma_angle", [])
+    t_series = hist.get("sense_sigma_t", []) or glyph.get("t", [])
+    rows_raw = zip_longest(
+        t_series, sigma_x, sigma_y, sigma_mag, sigma_angle, fillvalue=None
+    )
+
+    def _clean(value: float | None) -> float:
+        """Return ``0`` for ``None`` or ``NaN`` values."""
+        if value is None or (isinstance(value, float) and math.isnan(value)):
+            return 0
+        return value
+
+    def _gen_rows() -> Iterator[tuple[float, float, float, float, float]]:
+        for i, (t, x, y, m, a) in enumerate(rows_raw):
+            yield (
+                i if t is None else t,
+                _clean(x),
+                _clean(y),
+                _clean(m),
+                _clean(a),
+            )
+
+    rows_csv, rows_sigma = tee(_gen_rows())
+
+    sigma: SigmaTrace = {
+        "t": [],
+        "sigma_x": [],
+        "sigma_y": [],
+        "mag": [],
+        "angle": [],
+    }
+    for t, x, y, m, a in rows_sigma:
+        sigma["t"].append(t)
+        sigma["sigma_x"].append(x)
+        sigma["sigma_y"].append(y)
+        sigma["mag"].append(m)
+        sigma["angle"].append(a)
+    morph: Sequence[Mapping[str, float]] = hist.get("morph", [])
+    epi_supp: Sequence[Mapping[str, float]] = hist.get("EPI_support", [])
+    fmt = fmt.lower()
+    if fmt not in {"csv", "json"}:
+        raise ValueError(f"Unsupported export format: {fmt}")
+    if fmt == "csv":
+        specs: list[tuple[str, Sequence[str], Iterable[Sequence[object]]]] = [
+            (
+                "_glyphogram.csv",
+                ["t", *GLYPHS_CANONICAL],
+                _iter_glif_rows(glyph),
+            ),
+            (
+                "_sigma.csv",
+                ["t", "x", "y", "mag", "angle"],
+                ([t, x, y, m, a] for t, x, y, m, a in rows_csv),
+            ),
+        ]
+        if morph:
+            specs.append(
+                (
+                    "_morph.csv",
+                    ["t", "ID", "CM", "NE", "PP"],
+                    (
+                        [
+                            row.get("t"),
+                            row.get("ID"),
+                            row.get("CM"),
+                            row.get("NE"),
+                            row.get("PP"),
+                        ]
+                        for row in morph
+                    ),
+                )
+            )
+        if epi_supp:
+            specs.append(
+                (
+                    "_epi_support.csv",
+                    ["t", "size", "epi_norm"],
+                    (
+                        [row.get("t"), row.get("size"), row.get("epi_norm")]
+                        for row in epi_supp
+                    ),
+                )
+            )
+        for suffix, headers, rows in specs:
+            _write_csv(base_path + suffix, headers, rows, output_dir=output_dir)
+    else:
+        data = {
+            "glyphogram": glyph,
+            "sigma": sigma,
+            "morph": morph,
+            "epi_support": epi_supp,
+        }
+        json_path = base_path + ".json"
+
+        def _write_json(f: TextIO) -> None:
+            f.write(json_dumps(data))
+
+        safe_write(json_path, _write_json, base_dir=output_dir)

tnfr/metrics/export.pyi

@@ -0,0 +1,7 @@
+from ..config.constants import GLYPHS_CANONICAL as GLYPHS_CANONICAL
+from ..glyph_history import ensure_history as ensure_history
+from ..types import Graph as Graph, SigmaTrace as SigmaTrace
+from ..utils import json_dumps as json_dumps, safe_write as safe_write
+from .core import glyphogram_series as glyphogram_series
+
+def export_metrics(G: Graph, base_path: str, fmt: str = "csv") -> None: ...