tnfr 4.5.1__py3-none-any.whl → 6.0.0__py3-none-any.whl

tnfr/metrics/diagnosis.pyi

@@ -0,0 +1,89 @@
+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
+annotations: 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/export.py

@@ -0,0 +1,151 @@
+"""Metrics export."""
+
+from __future__ import annotations
+
+import csv
+import math
+from collections.abc import Iterable, Iterator, Sequence
+from itertools import zip_longest, tee
+from typing import Mapping, TextIO
+
+from ..config.constants import GLYPHS_CANONICAL
+from ..glyph_history import ensure_history
+from ..io import safe_write
+from ..utils import json_dumps
+from ..types import Graph
+from .core import glyphogram_series
+from .glyph_timing import SigmaTrace
+
+
+def _write_csv(
+    path: str,
+    headers: Sequence[str],
+    rows: Iterable[Sequence[object]],
+) -> 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="")
+
+
+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") -> None:
+    """Dump glyphogram and σ(t) trace to compact CSV or JSON files."""
+    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)
+    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)

tnfr/metrics/glyph_timing.py

@@ -0,0 +1,369 @@
+"""Glyph timing utilities and advanced metrics."""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass
+import math
+from types import ModuleType
+from typing import Any, Callable, Mapping, MutableMapping, MutableSequence, Sequence, TypedDict, cast
+
+from ..alias import get_attr
+from ..constants import get_aliases, get_param
+from ..config.constants import GLYPH_GROUPS, GLYPHS_CANONICAL
+from ..glyph_history import append_metric, last_glyph
+from ..types import GraphLike
+
+ALIAS_EPI = get_aliases("EPI")
+
+LATENT_GLYPH: str = "SHA"
+DEFAULT_EPI_SUPPORT_LIMIT = 0.05
+
+try:  # pragma: no cover - import guard exercised via tests
+    import numpy as _np  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover - numpy optional dependency
+    _np = None
+
+np: ModuleType | None = cast(ModuleType | None, _np)
+
+
+def _has_numpy_support(np_obj: object) -> bool:
+    """Return ``True`` when ``np_obj`` exposes the required NumPy API."""
+
+    return isinstance(np_obj, ModuleType) or (
+        np_obj is not None
+        and hasattr(np_obj, "fromiter")
+        and hasattr(np_obj, "bincount")
+    )
+
+
+class SigmaTrace(TypedDict):
+    """Time-aligned σ(t) trace exported alongside glyphograms."""
+
+    t: list[float]
+    sigma_x: list[float]
+    sigma_y: list[float]
+    mag: list[float]
+    angle: list[float]
+
+
+GlyphogramRow = MutableMapping[str, float]
+GlyphTimingTotals = MutableMapping[str, float]
+GlyphTimingByNode = MutableMapping[Any, MutableMapping[str, MutableSequence[float]]]
+GlyphCounts = Mapping[str, int]
+GlyphMetricsHistoryValue = MutableMapping[Any, Any] | MutableSequence[Any]
+GlyphMetricsHistory = MutableMapping[str, GlyphMetricsHistoryValue]
+MetricsListHistory = MutableMapping[str, list[Any]]
+
+_GLYPH_TO_INDEX = {glyph: idx for idx, glyph in enumerate(GLYPHS_CANONICAL)}
+
+
+def _coerce_float(value: Any) -> float:
+    """Attempt to coerce ``value`` to ``float`` returning ``0.0`` on failure."""
+
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+@dataclass
+class GlyphTiming:
+    curr: str | None = None
+    run: float = 0.0
+
+
+__all__ = [
+    "LATENT_GLYPH",
+    "GlyphTiming",
+    "SigmaTrace",
+    "GlyphogramRow",
+    "GlyphTimingTotals",
+    "GlyphTimingByNode",
+    "_tg_state",
+    "for_each_glyph",
+    "_update_tg_node",
+    "_update_tg",
+    "_update_glyphogram",
+    "_update_latency_index",
+    "_update_epi_support",
+    "_update_morph_metrics",
+    "_compute_advanced_metrics",
+]
+
+
+# ---------------------------------------------------------------------------
+# Internal utilities
+# ---------------------------------------------------------------------------
+
+
+def _count_glyphs_chunk(chunk: Sequence[str]) -> Counter[str]:
+    """Count glyph occurrences within a chunk (multiprocessing helper)."""
+
+    counter: Counter[str] = Counter()
+    for glyph in chunk:
+        counter[glyph] += 1
+    return counter
+
+
+def _epi_support_chunk(values: Sequence[float], threshold: float) -> tuple[float, int]:
+    """Compute EPI support contribution for a chunk."""
+
+    total = 0.0
+    count = 0
+    for value in values:
+        if value >= threshold:
+            total += value
+            count += 1
+    return total, count
+
+
+def _tg_state(nd: MutableMapping[str, Any]) -> GlyphTiming:
+    """Expose per-node glyph timing state."""
+
+    return nd.setdefault("_Tg", GlyphTiming())
+
+
+def for_each_glyph(fn: Callable[[str], None]) -> None:
+    """Apply ``fn`` to each canonical structural operator."""
+
+    for g in GLYPHS_CANONICAL:
+        fn(g)
+
+
+# ---------------------------------------------------------------------------
+# Glyph timing helpers
+# ---------------------------------------------------------------------------
+
+
+def _update_tg_node(
+    n: Any,
+    nd: MutableMapping[str, Any],
+    dt: float,
+    tg_total: GlyphTimingTotals,
+    tg_by_node: GlyphTimingByNode | None,
+) -> tuple[str | None, bool]:
+    """Track a node's glyph transition and accumulate run time."""
+
+    g = last_glyph(nd)
+    if not g:
+        return None, False
+    st = _tg_state(nd)
+    curr = st.curr
+    if curr is None:
+        st.curr = g
+        st.run = dt
+    elif g == curr:
+        st.run += dt
+    else:
+        dur = st.run
+        tg_total[curr] += dur
+        if tg_by_node is not None:
+            tg_by_node[n][curr].append(dur)
+        st.curr = g
+        st.run = dt
+    return g, g == LATENT_GLYPH
+
+
+def _update_tg(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    dt: float,
+    save_by_node: bool,
+    n_jobs: int | None = None,
+) -> tuple[Counter[str], int, int]:
+    """Accumulate glyph dwell times for the entire graph."""
+
+    tg_total = cast(GlyphTimingTotals, hist.setdefault("Tg_total", defaultdict(float)))
+    tg_by_node = (
+        cast(
+            GlyphTimingByNode,
+            hist.setdefault(
+                "Tg_by_node",
+                defaultdict(lambda: defaultdict(list)),
+            ),
+        )
+        if save_by_node
+        else None
+    )
+
+    n_total = 0
+    n_latent = 0
+    glyph_sequence: list[str] = []
+    for n, nd in G.nodes(data=True):
+        g, is_latent = _update_tg_node(n, nd, dt, tg_total, tg_by_node)
+        if g is None:
+            continue
+        n_total += 1
+        if is_latent:
+            n_latent += 1
+        glyph_sequence.append(g)
+
+    counts: Counter[str] = Counter()
+    if not glyph_sequence:
+        return counts, n_total, n_latent
+
+    if _has_numpy_support(np):
+        glyph_idx = np.fromiter(
+            (_GLYPH_TO_INDEX[glyph] for glyph in glyph_sequence),
+            dtype=np.int64,
+            count=len(glyph_sequence),
+        )
+        freq = np.bincount(glyph_idx, minlength=len(GLYPHS_CANONICAL))
+        counts.update(
+            {
+                glyph: int(freq[_GLYPH_TO_INDEX[glyph]])
+                for glyph in GLYPHS_CANONICAL
+                if freq[_GLYPH_TO_INDEX[glyph]]
+            }
+        )
+    elif n_jobs is not None and n_jobs > 1 and len(glyph_sequence) > 1:
+        chunk_size = max(1, math.ceil(len(glyph_sequence) / n_jobs))
+        futures = []
+        with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+            for start in range(0, len(glyph_sequence), chunk_size):
+                chunk = glyph_sequence[start:start + chunk_size]
+                futures.append(executor.submit(_count_glyphs_chunk, chunk))
+            for future in futures:
+                counts.update(future.result())
+    else:
+        counts.update(glyph_sequence)
+
+    return counts, n_total, n_latent
+
+
+def _update_glyphogram(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    counts: GlyphCounts,
+    t: float,
+    n_total: int,
+) -> None:
+    """Record glyphogram row from glyph counts."""
+
+    normalize_series = bool(get_param(G, "METRICS").get("normalize_series", False))
+    row: GlyphogramRow = {"t": t}
+    total = max(1, n_total)
+    for g in GLYPHS_CANONICAL:
+        c = counts.get(g, 0)
+        row[g] = (c / total) if normalize_series else c
+    append_metric(cast(MetricsListHistory, hist), "glyphogram", row)
+
+
+def _update_latency_index(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    n_total: int,
+    n_latent: int,
+    t: float,
+) -> None:
+    """Record latency index for the current step."""
+
+    li = n_latent / max(1, n_total)
+    append_metric(
+        cast(MetricsListHistory, hist),
+        "latency_index",
+        {"t": t, "value": li},
+    )
+
+
+def _update_epi_support(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    t: float,
+    threshold: float = DEFAULT_EPI_SUPPORT_LIMIT,
+    n_jobs: int | None = None,
+) -> None:
+    """Measure EPI support and normalized magnitude."""
+
+    node_count = G.number_of_nodes()
+    total = 0.0
+    count = 0
+
+    if _has_numpy_support(np) and node_count:
+        epi_values = np.fromiter(
+            (
+                abs(_coerce_float(get_attr(nd, ALIAS_EPI, 0.0)))
+                for _, nd in G.nodes(data=True)
+            ),
+            dtype=float,
+            count=node_count,
+        )
+        mask = epi_values >= threshold
+        count = int(mask.sum())
+        if count:
+            total = float(epi_values[mask].sum())
+    elif n_jobs is not None and n_jobs > 1 and node_count > 1:
+        values = [
+            abs(_coerce_float(get_attr(nd, ALIAS_EPI, 0.0)))
+            for _, nd in G.nodes(data=True)
+        ]
+        chunk_size = max(1, math.ceil(len(values) / n_jobs))
+        totals: list[tuple[float, int]] = []
+        with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+            futures = []
+            for start in range(0, len(values), chunk_size):
+                chunk = values[start:start + chunk_size]
+                futures.append(executor.submit(_epi_support_chunk, chunk, threshold))
+            for future in futures:
+                totals.append(future.result())
+        for part_total, part_count in totals:
+            total += part_total
+            count += part_count
+    else:
+        for _, nd in G.nodes(data=True):
+            epi_val = abs(_coerce_float(get_attr(nd, ALIAS_EPI, 0.0)))
+            if epi_val >= threshold:
+                total += epi_val
+                count += 1
+    epi_norm = (total / count) if count else 0.0
+    append_metric(
+        cast(MetricsListHistory, hist),
+        "EPI_support",
+        {"t": t, "size": count, "epi_norm": float(epi_norm)},
+    )
+
+
+def _update_morph_metrics(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    counts: GlyphCounts,
+    t: float,
+) -> None:
+    """Capture morphosyntactic distribution of glyphs."""
+
+    def get_count(keys: Sequence[str]) -> int:
+        return sum(counts.get(k, 0) for k in keys)
+
+    total = max(1, sum(counts.values()))
+    id_val = get_count(GLYPH_GROUPS.get("ID", ())) / total
+    cm_val = get_count(GLYPH_GROUPS.get("CM", ())) / total
+    ne_val = get_count(GLYPH_GROUPS.get("NE", ())) / total
+    num = get_count(GLYPH_GROUPS.get("PP_num", ()))
+    den = get_count(GLYPH_GROUPS.get("PP_den", ()))
+    pp_val = 0.0 if den == 0 else num / den
+    append_metric(
+        cast(MetricsListHistory, hist),
+        "morph",
+        {"t": t, "ID": id_val, "CM": cm_val, "NE": ne_val, "PP": pp_val},
+    )
+
+
+def _compute_advanced_metrics(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    t: float,
+    dt: float,
+    cfg: Mapping[str, Any],
+    threshold: float = DEFAULT_EPI_SUPPORT_LIMIT,
+    n_jobs: int | None = None,
+) -> None:
+    """Compute glyph timing derived metrics."""
+
+    save_by_node = bool(cfg.get("save_by_node", True))
+    counts, n_total, n_latent = _update_tg(G, hist, dt, save_by_node, n_jobs=n_jobs)
+    _update_glyphogram(G, hist, counts, t, n_total)
+    _update_latency_index(G, hist, n_total, n_latent, t)
+    _update_epi_support(G, hist, t, threshold, n_jobs=n_jobs)
+    _update_morph_metrics(G, hist, counts, t)