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

tnfr/metrics/glyph_timing.py

@@ -0,0 +1,189 @@
+"""Glyph timing utilities and advanced metrics."""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from ..alias import get_attr
+from ..constants import get_aliases, get_param
+from ..constants_glyphs import GLYPH_GROUPS, GLYPHS_CANONICAL
+from ..glyph_history import append_metric, last_glyph
+from ..types import Glyph
+
+ALIAS_EPI = get_aliases("EPI")
+
+LATENT_GLYPH = Glyph.SHA.value
+DEFAULT_EPI_SUPPORT_LIMIT = 0.05
+
+
+@dataclass
+class GlyphTiming:
+    curr: str | None = None
+    run: float = 0.0
+
+
+__all__ = [
+    "LATENT_GLYPH",
+    "GlyphTiming",
+    "_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 _tg_state(nd: dict[str, Any]) -> GlyphTiming:
+    """Expose per-node glyph timing state."""
+
+    return nd.setdefault("_Tg", GlyphTiming())
+
+
+def for_each_glyph(fn: Callable[[str], Any]) -> None:
+    """Apply ``fn`` to each canonical structural operator."""
+
+    for g in GLYPHS_CANONICAL:
+        fn(g)
+
+
+# ---------------------------------------------------------------------------
+# Glyph timing helpers
+# ---------------------------------------------------------------------------
+
+
+def _update_tg_node(n, nd, dt, tg_total, tg_by_node):
+    """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, hist, dt, save_by_node: bool):
+    """Accumulate glyph dwell times for the entire graph."""
+
+    counts = Counter()
+    tg_total = hist.setdefault("Tg_total", defaultdict(float))
+    tg_by_node = (
+        hist.setdefault("Tg_by_node", defaultdict(lambda: defaultdict(list)))
+        if save_by_node
+        else None
+    )
+
+    n_total = 0
+    n_latent = 0
+    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
+        counts[g] += 1
+    return counts, n_total, n_latent
+
+
+def _update_glyphogram(G, hist, counts, t, n_total):
+    """Record glyphogram row from glyph counts."""
+
+    normalize_series = bool(get_param(G, "METRICS").get("normalize_series", False))
+    row = {"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(hist, "glyphogram", row)
+
+
+def _update_latency_index(G, hist, n_total, n_latent, t):
+    """Record latency index for the current step."""
+
+    li = n_latent / max(1, n_total)
+    append_metric(hist, "latency_index", {"t": t, "value": li})
+
+
+def _update_epi_support(
+    G,
+    hist,
+    t,
+    threshold: float = DEFAULT_EPI_SUPPORT_LIMIT,
+):
+    """Measure EPI support and normalized magnitude."""
+
+    total = 0.0
+    count = 0
+    for _, nd in G.nodes(data=True):
+        epi_val = abs(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(
+        hist,
+        "EPI_support",
+        {"t": t, "size": count, "epi_norm": float(epi_norm)},
+    )
+
+
+def _update_morph_metrics(G, hist, counts, t):
+    """Capture morphosyntactic distribution of glyphs."""
+
+    def get_count(keys):
+        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(
+        hist,
+        "morph",
+        {"t": t, "ID": id_val, "CM": cm_val, "NE": ne_val, "PP": pp_val},
+    )
+
+
+def _compute_advanced_metrics(
+    G,
+    hist,
+    t,
+    dt,
+    cfg,
+    threshold: float = DEFAULT_EPI_SUPPORT_LIMIT,
+):
+    """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)
+    _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)
+    _update_morph_metrics(G, hist, counts, t)

tnfr/metrics/reporting.py

@@ -0,0 +1,148 @@
+"""Reporting helpers for collected metrics."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from heapq import nlargest
+from statistics import mean, fmean, StatisticsError
+
+from ..glyph_history import ensure_history
+from ..sense import sigma_rose
+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, 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):
+        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, n, normalize: bool = False) -> dict[str, float | list[float]]:
+    """Per-node glyph dwell summary."""
+
+    hist = ensure_history(G)
+    rec = hist.get("Tg_by_node", {}).get(n, {})
+    if not normalize:
+        out: dict[str, list[float]] = {}
+
+        def copy_runs(g):
+            out[g] = list(rec.get(g, []))
+
+        for_each_glyph(copy_runs)
+        return out
+    out: dict[str, float] = {}
+
+    def add(g):
+        runs = rec.get(g, [])
+        out[g] = float(mean(runs)) if runs else 0.0
+
+    for_each_glyph(add)
+    return out
+
+
+def latency_series(G) -> dict[str, list[float]]:
+    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) -> dict[str, list[float]]:
+    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):
+        out[g] = [float(x.get(g, 0.0)) for x in xs]
+
+    for_each_glyph(add)
+    return out
+
+
+def glyph_top(G, 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, *, series_limit: int | None = None
+) -> tuple[dict[str, Any], bool]:
+    """Collect a compact metrics summary for CLI reporting.
+
+    Parameters
+    ----------
+    G:
+        Graph containing the recorded metrics.
+    series_limit:
+        Maximum number of samples to keep for each glyphogram series. ``None`` or
+        non-positive values disable trimming and return 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: list[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/sense_index.py

@@ -0,0 +1,120 @@
+"""Sense index helpers."""
+
+from __future__ import annotations
+
+import math
+from functools import partial
+from typing import Any
+
+from ..alias import get_attr, set_attr
+from ..collections_utils import normalize_weights
+from ..constants import get_aliases
+from ..cache import edge_version_cache, stable_json
+from ..helpers.numeric import angle_diff, clamp01
+from .trig import neighbor_phase_mean_list
+from ..import_utils import get_numpy
+from ..types import GraphLike
+
+from .common import (
+    ensure_neighbors_map,
+    merge_graph_weights,
+    _get_vf_dnfr_max,
+)
+from .trig_cache import get_trig_cache
+
+ALIAS_VF = get_aliases("VF")
+ALIAS_DNFR = get_aliases("DNFR")
+ALIAS_SI = get_aliases("SI")
+ALIAS_THETA = get_aliases("THETA")
+
+__all__ = ("get_Si_weights", "compute_Si_node", "compute_Si")
+
+
+def _cache_weights(G: GraphLike) -> tuple[float, float, float]:
+    """Normalise and cache Si weights, delegating persistence."""
+
+    w = merge_graph_weights(G, "SI_WEIGHTS")
+    cfg_key = stable_json(w)
+
+    def builder() -> tuple[float, float, float]:
+        weights = normalize_weights(w, ("alpha", "beta", "gamma"), default=0.0)
+        alpha = weights["alpha"]
+        beta = weights["beta"]
+        gamma = weights["gamma"]
+        G.graph["_Si_weights"] = weights
+        G.graph["_Si_weights_key"] = cfg_key
+        G.graph["_Si_sensitivity"] = {
+            "dSi_dvf_norm": alpha,
+            "dSi_ddisp_fase": -beta,
+            "dSi_ddnfr_norm": -gamma,
+        }
+        return alpha, beta, gamma
+
+    return edge_version_cache(G, ("_Si_weights", cfg_key), builder)
+
+
+def get_Si_weights(G: GraphLike) -> tuple[float, float, float]:
+    """Obtain and normalise weights for the sense index."""
+
+    return _cache_weights(G)
+
+
+def compute_Si_node(
+    n: Any,
+    nd: dict[str, Any],
+    *,
+    alpha: float,
+    beta: float,
+    gamma: float,
+    vfmax: float,
+    dnfrmax: float,
+    disp_fase: float,
+    inplace: bool,
+) -> float:
+    """Compute ``Si`` for a single node."""
+
+    vf = get_attr(nd, ALIAS_VF, 0.0)
+    vf_norm = clamp01(abs(vf) / vfmax)
+
+    dnfr = get_attr(nd, ALIAS_DNFR, 0.0)
+    dnfr_norm = clamp01(abs(dnfr) / dnfrmax)
+
+    Si = alpha * vf_norm + beta * (1.0 - disp_fase) + gamma * (1.0 - dnfr_norm)
+    Si = clamp01(Si)
+    if inplace:
+        set_attr(nd, ALIAS_SI, Si)
+    return Si
+
+
+def compute_Si(G: GraphLike, *, inplace: bool = True) -> dict[Any, float]:
+    """Compute ``Si`` per node and optionally store it on the graph."""
+
+    neighbors = ensure_neighbors_map(G)
+    alpha, beta, gamma = get_Si_weights(G)
+    vfmax, dnfrmax = _get_vf_dnfr_max(G)
+
+    np = get_numpy()
+    trig = get_trig_cache(G, np=np)
+    cos_th, sin_th, thetas = trig.cos, trig.sin, trig.theta
+
+    pm_fn = partial(
+        neighbor_phase_mean_list, cos_th=cos_th, sin_th=sin_th, np=np
+    )
+
+    out: dict[Any, float] = {}
+    for n, nd in G.nodes(data=True):
+        neigh = neighbors[n]
+        th_bar = pm_fn(neigh, fallback=thetas[n])
+        disp_fase = abs(angle_diff(thetas[n], th_bar)) / math.pi
+        out[n] = compute_Si_node(
+            n,
+            nd,
+            alpha=alpha,
+            beta=beta,
+            gamma=gamma,
+            vfmax=vfmax,
+            dnfrmax=dnfrmax,
+            disp_fase=disp_fase,
+            inplace=inplace,
+        )
+    return out

tnfr/metrics/trig.py

@@ -0,0 +1,181 @@
+"""Trigonometric helpers shared across metrics and helpers.
+
+This module focuses on mathematical utilities (means, compensated sums, etc.).
+Caching of cosine/sine values lives in :mod:`tnfr.metrics.trig_cache`.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Sequence
+from itertools import tee
+from typing import Any
+
+from ..import_utils import cached_import, get_numpy
+from ..helpers.numeric import kahan_sum_nd
+
+__all__ = (
+    "accumulate_cos_sin",
+    "_phase_mean_from_iter",
+    "_neighbor_phase_mean_core",
+    "_neighbor_phase_mean_generic",
+    "neighbor_phase_mean_list",
+    "neighbor_phase_mean",
+)
+
+
+def accumulate_cos_sin(
+    it: Iterable[tuple[float, float] | None],
+) -> tuple[float, float, bool]:
+    """Accumulate cosine and sine pairs with compensated summation.
+
+    ``it`` yields optional ``(cos, sin)`` tuples. Entries with ``None``
+    components are ignored. The returned values are the compensated sums of
+    cosines and sines along with a flag indicating whether any pair was
+    processed.
+    """
+
+    processed = False
+
+    def iter_real_pairs():
+        nonlocal processed
+        for cs in it:
+            if cs is None:
+                continue
+            c, s = cs
+            if c is None or s is None:
+                continue
+            try:
+                c_val = float(c)
+                s_val = float(s)
+            except (TypeError, ValueError):
+                continue
+            if not (math.isfinite(c_val) and math.isfinite(s_val)):
+                continue
+            processed = True
+            yield (c_val, s_val)
+
+    sum_cos, sum_sin = kahan_sum_nd(iter_real_pairs(), dims=2)
+
+    if not processed:
+        return 0.0, 0.0, False
+
+    return sum_cos, sum_sin, True
+
+
+def _phase_mean_from_iter(
+    it: Iterable[tuple[float, float] | None], fallback: float
+) -> float:
+    """Return circular mean from an iterator of cosine/sine pairs.
+
+    ``it`` yields optional ``(cos, sin)`` tuples. ``fallback`` is returned if
+    no valid pairs are processed.
+    """
+
+    sum_cos, sum_sin, processed = accumulate_cos_sin(it)
+    if not processed:
+        return fallback
+    return math.atan2(sum_sin, sum_cos)
+
+
+def _neighbor_phase_mean_core(
+    neigh: Sequence[Any],
+    cos_map: dict[Any, float],
+    sin_map: dict[Any, float],
+    np,
+    fallback: float,
+) -> float:
+    """Return circular mean of neighbour phases given trig mappings."""
+
+    def _iter_pairs():
+        for v in neigh:
+            c = cos_map.get(v)
+            s = sin_map.get(v)
+            if c is not None and s is not None:
+                yield c, s
+
+    pairs = _iter_pairs()
+
+    if np is not None:
+        cos_iter, sin_iter = tee(pairs, 2)
+        cos_arr = np.fromiter((c for c, _ in cos_iter), dtype=float)
+        sin_arr = np.fromiter((s for _, s in sin_iter), dtype=float)
+        if cos_arr.size:
+            mean_cos = float(np.mean(cos_arr))
+            mean_sin = float(np.mean(sin_arr))
+            return float(np.arctan2(mean_sin, mean_cos))
+        return fallback
+
+    sum_cos, sum_sin, processed = accumulate_cos_sin(pairs)
+    if not processed:
+        return fallback
+    return math.atan2(sum_sin, sum_cos)
+
+
+def _neighbor_phase_mean_generic(
+    obj,
+    cos_map: dict[Any, float] | None = None,
+    sin_map: dict[Any, float] | None = None,
+    np=None,
+    fallback: float = 0.0,
+) -> float:
+    """Internal helper delegating to :func:`_neighbor_phase_mean_core`.
+
+    ``obj`` may be either a node bound to a graph or a sequence of neighbours.
+    When ``cos_map`` and ``sin_map`` are ``None`` the function assumes ``obj`` is
+    a node and obtains the required trigonometric mappings from the cached
+    structures. Otherwise ``obj`` is treated as an explicit neighbour
+    sequence and ``cos_map``/``sin_map`` must be provided.
+    """
+
+    if np is None:
+        np = get_numpy()
+
+    if cos_map is None or sin_map is None:
+        node = obj
+        if getattr(node, "G", None) is None:
+            raise TypeError(
+                "neighbor_phase_mean requires nodes bound to a graph"
+            )
+        from .trig_cache import get_trig_cache
+
+        trig = get_trig_cache(node.G)
+        fallback = trig.theta.get(node.n, fallback)
+        cos_map = trig.cos
+        sin_map = trig.sin
+        neigh = node.G[node.n]
+    else:
+        neigh = obj
+
+    return _neighbor_phase_mean_core(neigh, cos_map, sin_map, np, fallback)
+
+
+def neighbor_phase_mean_list(
+    neigh: Sequence[Any],
+    cos_th: dict[Any, float],
+    sin_th: dict[Any, float],
+    np=None,
+    fallback: float = 0.0,
+) -> float:
+    """Return circular mean of neighbour phases from cosine/sine mappings.
+
+    This is a thin wrapper over :func:`_neighbor_phase_mean_generic` that
+    operates on explicit neighbour lists.
+    """
+
+    return _neighbor_phase_mean_generic(
+        neigh, cos_map=cos_th, sin_map=sin_th, np=np, fallback=fallback
+    )
+
+
+def neighbor_phase_mean(obj, n=None) -> float:
+    """Circular mean of neighbour phases.
+
+    The :class:`NodoNX` import is cached after the first call.
+    """
+
+    NodoNX = cached_import("tnfr.node", "NodoNX")
+    if NodoNX is None:
+        raise ImportError("NodoNX is unavailable")
+    node = NodoNX(obj, n) if n is not None else obj
+    return _neighbor_phase_mean_generic(node)