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

tnfr/metrics/reporting.py

@@ -0,0 +1,152 @@
+"""Reporting helpers for collected metrics."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from heapq import nlargest
+from statistics import mean, fmean, StatisticsError
+
+from ..glyph_history import ensure_history
+from ..types import NodeId, TNFRGraph
+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: 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]]:
+    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]]:
+    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.
+
+    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: 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,12 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+Tg_by_node: Any
+Tg_global: Any
+build_metrics_summary: Any
+glyph_top: Any
+glyphogram_series: Any
+latency_series: Any

tnfr/metrics/sense_index.py

@@ -0,0 +1,294 @@
+"""Sense index helpers."""
+
+from __future__ import annotations
+
+import math
+from concurrent.futures import ProcessPoolExecutor
+from functools import partial
+from typing import Any, Iterable, Mapping
+
+from ..alias import get_attr, set_attr
+from ..constants import get_aliases
+from ..helpers.numeric import angle_diff, clamp01
+from ..types import GraphLike
+from ..utils import (
+    edge_version_cache,
+    get_numpy,
+    normalize_weights,
+    stable_json,
+)
+from .trig import neighbor_phase_mean_list
+
+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")
+
+PHASE_DISPERSION_KEY = "dSi_dphase_disp"
+_VALID_SENSITIVITY_KEYS = frozenset(
+    {"dSi_dvf_norm", PHASE_DISPERSION_KEY, "dSi_ddnfr_norm"}
+)
+__all__ = ("get_Si_weights", "compute_Si_node", "compute_Si")
+
+
+def _normalise_si_sensitivity_mapping(
+    mapping: Mapping[str, float], *, warn: bool
+) -> dict[str, float]:
+    """Return a mapping containing only supported Si sensitivity keys."""
+
+    normalised = dict(mapping)
+    _ = warn  # kept for API compatibility with trace helpers
+    unexpected = sorted(k for k in normalised if k not in _VALID_SENSITIVITY_KEYS)
+    if unexpected:
+        allowed = ", ".join(sorted(_VALID_SENSITIVITY_KEYS))
+        received = ", ".join(unexpected)
+        raise ValueError(
+            "Si sensitivity mappings accept only {%s}; unexpected key(s): %s"
+            % (allowed, received)
+        )
+    return normalised
+
+
+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)
+
+    existing = G.graph.get("_Si_sensitivity")
+    if isinstance(existing, Mapping):
+        migrated = _normalise_si_sensitivity_mapping(existing, warn=True)
+        if migrated != existing:
+            G.graph["_Si_sensitivity"] = migrated
+
+    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,
+            PHASE_DISPERSION_KEY: -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,
+    phase_dispersion: float | None = None,
+    inplace: bool,
+    **kwargs: Any,
+) -> float:
+    """Compute ``Si`` for a single node."""
+
+    if kwargs:
+        unexpected = ", ".join(sorted(kwargs))
+        raise TypeError(f"Unexpected keyword argument(s): {unexpected}")
+
+    if phase_dispersion is None:
+        raise TypeError("Missing required keyword-only argument: 'phase_dispersion'")
+
+    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 - phase_dispersion)
+        + gamma * (1.0 - dnfr_norm)
+    )
+    Si = clamp01(Si)
+    if inplace:
+        set_attr(nd, ALIAS_SI, Si)
+    return Si
+
+
+def _coerce_jobs(raw_jobs: Any | None) -> int | None:
+    """Normalise ``n_jobs`` values coming from user configuration."""
+
+    try:
+        jobs = None if raw_jobs is None else int(raw_jobs)
+    except (TypeError, ValueError):
+        return None
+    if jobs is not None and jobs <= 0:
+        return None
+    return jobs
+
+
+def _compute_si_python_chunk(
+    chunk: Iterable[tuple[Any, tuple[Any, ...], float, float, float]],
+    *,
+    cos_th: dict[Any, float],
+    sin_th: dict[Any, float],
+    alpha: float,
+    beta: float,
+    gamma: float,
+    vfmax: float,
+    dnfrmax: float,
+) -> dict[Any, float]:
+    """Compute Si values for a chunk of nodes using pure Python math."""
+
+    results: dict[Any, float] = {}
+    for n, neigh, theta, vf, dnfr in chunk:
+        th_bar = neighbor_phase_mean_list(
+            neigh, cos_th=cos_th, sin_th=sin_th, np=None, fallback=theta
+        )
+        phase_dispersion = abs(angle_diff(theta, th_bar)) / math.pi
+        vf_norm = clamp01(abs(vf) / vfmax)
+        dnfr_norm = clamp01(abs(dnfr) / dnfrmax)
+        Si = (
+            alpha * vf_norm
+            + beta * (1.0 - phase_dispersion)
+            + gamma * (1.0 - dnfr_norm)
+        )
+        results[n] = clamp01(Si)
+    return results
+
+
+def compute_Si(
+    G: GraphLike,
+    *,
+    inplace: bool = True,
+    n_jobs: int | None = None,
+) -> 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
+    )
+
+    if n_jobs is None:
+        n_jobs = _coerce_jobs(G.graph.get("SI_N_JOBS"))
+    else:
+        n_jobs = _coerce_jobs(n_jobs)
+
+    supports_vector = (
+        np is not None
+        and hasattr(np, "ndarray")
+        and all(hasattr(np, attr) for attr in ("fromiter", "abs", "clip", "remainder"))
+    )
+
+    nodes_data = list(G.nodes(data=True))
+    if not nodes_data:
+        return {}
+
+    if supports_vector:
+        node_ids: list[Any] = []
+        theta_vals: list[float] = []
+        mean_vals: list[float] = []
+        vf_vals: list[float] = []
+        dnfr_vals: list[float] = []
+        for n, nd in nodes_data:
+            theta = thetas.get(n, 0.0)
+            neigh = neighbors[n]
+            node_ids.append(n)
+            theta_vals.append(theta)
+            mean_vals.append(pm_fn(neigh, fallback=theta))
+            vf_vals.append(get_attr(nd, ALIAS_VF, 0.0))
+            dnfr_vals.append(get_attr(nd, ALIAS_DNFR, 0.0))
+
+        count = len(node_ids)
+        theta_arr = np.fromiter(theta_vals, dtype=float, count=count)
+        mean_arr = np.fromiter(mean_vals, dtype=float, count=count)
+        diff = np.remainder(theta_arr - mean_arr + math.pi, math.tau) - math.pi
+        phase_dispersion_arr = np.abs(diff) / math.pi
+
+        vf_arr = np.fromiter(vf_vals, dtype=float, count=count)
+        dnfr_arr = np.fromiter(dnfr_vals, dtype=float, count=count)
+        vf_norm = np.clip(np.abs(vf_arr) / vfmax, 0.0, 1.0)
+        dnfr_norm = np.clip(np.abs(dnfr_arr) / dnfrmax, 0.0, 1.0)
+
+        si_arr = np.clip(
+            alpha * vf_norm + beta * (1.0 - phase_dispersion_arr)
+            + gamma * (1.0 - dnfr_norm),
+            0.0,
+            1.0,
+        )
+
+        out = {node_ids[i]: float(si_arr[i]) for i in range(count)}
+    else:
+        out: dict[Any, float] = {}
+        if n_jobs is not None and n_jobs > 1:
+            node_payload: list[tuple[Any, tuple[Any, ...], float, float, float]] = []
+            for n, nd in nodes_data:
+                theta = thetas.get(n, 0.0)
+                vf = float(get_attr(nd, ALIAS_VF, 0.0))
+                dnfr = float(get_attr(nd, ALIAS_DNFR, 0.0))
+                neigh = neighbors[n]
+                node_payload.append((n, tuple(neigh), theta, vf, dnfr))
+
+            if node_payload:
+                chunk_size = math.ceil(len(node_payload) / n_jobs)
+                with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+                    futures = [
+                        executor.submit(
+                            _compute_si_python_chunk,
+                            node_payload[idx:idx + chunk_size],
+                            cos_th=cos_th,
+                            sin_th=sin_th,
+                            alpha=alpha,
+                            beta=beta,
+                            gamma=gamma,
+                            vfmax=vfmax,
+                            dnfrmax=dnfrmax,
+                        )
+                        for idx in range(0, len(node_payload), chunk_size)
+                    ]
+                    for future in futures:
+                        out.update(future.result())
+        else:
+            for n, nd in nodes_data:
+                theta = thetas.get(n, 0.0)
+                neigh = neighbors[n]
+                th_bar = pm_fn(neigh, fallback=theta)
+                phase_dispersion = abs(angle_diff(theta, th_bar)) / math.pi
+                out[n] = compute_Si_node(
+                    n,
+                    nd,
+                    alpha=alpha,
+                    beta=beta,
+                    gamma=gamma,
+                    vfmax=vfmax,
+                    dnfrmax=dnfrmax,
+                    phase_dispersion=phase_dispersion,
+                    inplace=False,
+                )
+
+    if inplace:
+        for n, value in out.items():
+            set_attr(G.nodes[n], ALIAS_SI, value)
+    return out

tnfr/metrics/sense_index.pyi

@@ -0,0 +1,9 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+compute_Si: Any
+compute_Si_node: Any
+get_Si_weights: Any

tnfr/metrics/trig.py

@@ -0,0 +1,216 @@
+"""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, Iterator, Sequence
+from itertools import tee
+from typing import TYPE_CHECKING, Any, overload, cast
+
+from ..helpers.numeric import kahan_sum_nd
+from ..utils import cached_import, get_numpy
+from ..types import NodeId, Phase, TNFRGraph
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from ..node import NodeProtocol
+
+__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() -> Iterator[tuple[float, float]]:
+        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: Any | None,
+    fallback: float,
+) -> float:
+    """Return circular mean of neighbour phases given trig mappings."""
+
+    def _iter_pairs() -> Iterator[tuple[float, float]]:
+        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: "NodeProtocol" | Sequence[Any],
+    cos_map: dict[Any, float] | None = None,
+    sin_map: dict[Any, float] | None = None,
+    np: Any | None = 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 = cast("NodeProtocol", 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 = cast(Sequence[Any], 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: Any | None = 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
+    )
+
+
+@overload
+def neighbor_phase_mean(obj: "NodeProtocol", n: None = ...) -> Phase:
+    ...
+
+
+@overload
+def neighbor_phase_mean(obj: TNFRGraph, n: NodeId) -> Phase:
+    ...
+
+
+def neighbor_phase_mean(
+    obj: "NodeProtocol" | TNFRGraph, n: NodeId | None = None
+) -> Phase:
+    """Circular mean of neighbour phases for ``obj``.
+
+    Parameters
+    ----------
+    obj:
+        Either a :class:`~tnfr.node.NodeProtocol` instance bound to a graph or a
+        :class:`~tnfr.types.TNFRGraph` from which the node ``n`` will be wrapped.
+    n:
+        Optional node identifier. Required when ``obj`` is a graph. Providing a
+        node identifier for a node object raises :class:`TypeError`.
+    """
+
+    NodeNX = cached_import("tnfr.node", "NodeNX")
+    if NodeNX is None:
+        raise ImportError("NodeNX is unavailable")
+    if n is None:
+        if hasattr(obj, "nodes"):
+            raise TypeError(
+                "neighbor_phase_mean requires a node identifier when passing a graph"
+            )
+        node = obj
+    else:
+        if hasattr(obj, "nodes"):
+            node = NodeNX(obj, n)
+        else:
+            raise TypeError(
+                "neighbor_phase_mean received a node and an explicit identifier"
+            )
+    return _neighbor_phase_mean_generic(node)

tnfr/metrics/trig.pyi

@@ -0,0 +1,12 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+_neighbor_phase_mean_core: Any
+_neighbor_phase_mean_generic: Any
+_phase_mean_from_iter: Any
+accumulate_cos_sin: Any
+neighbor_phase_mean: Any
+neighbor_phase_mean_list: Any