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

tnfr/metrics/common.py

@@ -0,0 +1,149 @@
+"""Shared helpers for TNFR metrics."""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import Any, Iterable, Mapping, Sequence
+
+from ..alias import collect_attr, get_attr, multi_recompute_abs_max
+from ..constants import DEFAULTS, get_aliases
+from ..helpers.numeric import clamp01, kahan_sum_nd
+from ..types import GraphLike
+from ..utils import edge_version_cache, get_numpy, normalize_weights
+
+ALIAS_DNFR = get_aliases("DNFR")
+ALIAS_D2EPI = get_aliases("D2EPI")
+ALIAS_DEPI = get_aliases("DEPI")
+ALIAS_VF = get_aliases("VF")
+
+__all__ = (
+    "GraphLike",
+    "compute_coherence",
+    "compute_dnfr_accel_max",
+    "normalize_dnfr",
+    "ensure_neighbors_map",
+    "merge_graph_weights",
+    "merge_and_normalize_weights",
+    "min_max_range",
+    "_get_vf_dnfr_max",
+)
+
+
+def compute_coherence(
+    G: GraphLike, *, return_means: bool = False
+) -> float | tuple[float, float, float]:
+    """Compute global coherence ``C`` from ``ΔNFR`` and ``dEPI``."""
+
+    count = G.number_of_nodes()
+    if count == 0:
+        return (0.0, 0.0, 0.0) if return_means else 0.0
+
+    nodes = G.nodes
+    np = get_numpy()
+    dnfr_values = collect_attr(G, nodes, ALIAS_DNFR, 0.0, np=np)
+    depi_values = collect_attr(G, nodes, ALIAS_DEPI, 0.0, np=np)
+
+    if np is not None:
+        dnfr_mean = float(np.mean(np.abs(dnfr_values)))
+        depi_mean = float(np.mean(np.abs(depi_values)))
+    else:
+        dnfr_sum, depi_sum = kahan_sum_nd(
+            ((abs(d), abs(e)) for d, e in zip(dnfr_values, depi_values)),
+            dims=2,
+        )
+        dnfr_mean = dnfr_sum / count
+        depi_mean = depi_sum / count
+
+    coherence = 1.0 / (1.0 + dnfr_mean + depi_mean)
+    return (coherence, dnfr_mean, depi_mean) if return_means else coherence
+
+
+def ensure_neighbors_map(G: GraphLike) -> Mapping[Any, Sequence[Any]]:
+    """Return cached neighbors list keyed by node as a read-only mapping."""
+
+    def builder() -> Mapping[Any, Sequence[Any]]:
+        return MappingProxyType({n: tuple(G.neighbors(n)) for n in G})
+
+    return edge_version_cache(G, "_neighbors", builder)
+
+
+def merge_graph_weights(G: GraphLike, key: str) -> dict[str, float]:
+    """Merge default weights for ``key`` with any graph overrides."""
+
+    return {**DEFAULTS[key], **G.graph.get(key, {})}
+
+
+def merge_and_normalize_weights(
+    G: GraphLike,
+    key: str,
+    fields: Sequence[str],
+    *,
+    default: float = 0.0,
+) -> dict[str, float]:
+    """Merge defaults for ``key`` and normalise ``fields``."""
+
+    w = merge_graph_weights(G, key)
+    return normalize_weights(
+        w,
+        fields,
+        default=default,
+        error_on_conversion=False,
+        error_on_negative=False,
+        warn_once=True,
+    )
+
+
+def compute_dnfr_accel_max(G: GraphLike) -> dict[str, float]:
+    """Compute absolute maxima of |ΔNFR| and |d²EPI/dt²|."""
+
+    return multi_recompute_abs_max(
+        G, {"dnfr_max": ALIAS_DNFR, "accel_max": ALIAS_D2EPI}
+    )
+
+
+def normalize_dnfr(nd: Mapping[str, Any], max_val: float) -> float:
+    """Normalise ``|ΔNFR|`` using ``max_val``."""
+
+    if max_val <= 0:
+        return 0.0
+    val = abs(get_attr(nd, ALIAS_DNFR, 0.0))
+    return clamp01(val / max_val)
+
+
+def min_max_range(
+    values: Iterable[float], *, default: tuple[float, float] = (0.0, 0.0)
+) -> tuple[float, float]:
+    """Return the minimum and maximum values observed in ``values``."""
+
+    it = iter(values)
+    try:
+        first = next(it)
+    except StopIteration:
+        return default
+    min_val = max_val = first
+    for val in it:
+        if val < min_val:
+            min_val = val
+        elif val > max_val:
+            max_val = val
+    return min_val, max_val
+
+
+def _get_vf_dnfr_max(G: GraphLike) -> tuple[float, float]:
+    """Ensure and return absolute maxima for ``νf`` and ``ΔNFR``."""
+
+    vfmax = G.graph.get("_vfmax")
+    dnfrmax = G.graph.get("_dnfrmax")
+    if vfmax is None or dnfrmax is None:
+        maxes = multi_recompute_abs_max(
+            G, {"_vfmax": ALIAS_VF, "_dnfrmax": ALIAS_DNFR}
+        )
+        if vfmax is None:
+            vfmax = maxes["_vfmax"]
+        if dnfrmax is None:
+            dnfrmax = maxes["_dnfrmax"]
+        G.graph["_vfmax"] = vfmax
+        G.graph["_dnfrmax"] = dnfrmax
+    vfmax = 1.0 if vfmax == 0 else vfmax
+    dnfrmax = 1.0 if dnfrmax == 0 else dnfrmax
+    return float(vfmax), float(dnfrmax)

tnfr/metrics/common.pyi

@@ -0,0 +1,15 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+GraphLike: Any
+_get_vf_dnfr_max: Any
+compute_coherence: Any
+compute_dnfr_accel_max: Any
+ensure_neighbors_map: Any
+merge_and_normalize_weights: Any
+merge_graph_weights: Any
+min_max_range: Any
+normalize_dnfr: Any

tnfr/metrics/core.py

@@ -0,0 +1,259 @@
+"""Basic metrics orchestrator."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, NamedTuple, cast
+
+from ..types import (
+    GlyphSelector,
+    NodeId,
+    SelectorPreselectionChoices,
+    SelectorPreselectionMetrics,
+    SelectorPreselectionPayload,
+    TNFRGraph,
+    TraceCallback,
+    TraceFieldFn,
+    TraceFieldMap,
+    TraceFieldRegistry,
+)
+
+from ..callback_utils import CallbackEvent, callback_manager
+from ..constants import get_param
+from ..glyph_history import append_metric, ensure_history
+from ..utils import get_logger
+from ..telemetry.verbosity import (
+    TelemetryVerbosity,
+    TELEMETRY_VERBOSITY_DEFAULT,
+    TELEMETRY_VERBOSITY_LEVELS,
+)
+from .coherence import (
+    _aggregate_si,
+    _track_stability,
+    _update_coherence,
+    _update_phase_sync,
+    _update_sigma,
+    register_coherence_callbacks,
+    GLYPH_LOAD_STABILIZERS_KEY,
+)
+from .diagnosis import register_diagnosis_callbacks
+from .glyph_timing import _compute_advanced_metrics, GlyphMetricsHistory
+from .reporting import (
+    Tg_by_node,
+    Tg_global,
+    glyphogram_series,
+    glyph_top,
+    latency_series,
+)
+
+logger = get_logger(__name__)
+
+__all__ = [
+    "TNFRGraph",
+    "NodeId",
+    "GlyphSelector",
+    "SelectorPreselectionMetrics",
+    "SelectorPreselectionChoices",
+    "SelectorPreselectionPayload",
+    "TraceCallback",
+    "TraceFieldFn",
+    "TraceFieldMap",
+    "TraceFieldRegistry",
+    "_metrics_step",
+    "register_metrics_callbacks",
+    "Tg_global",
+    "Tg_by_node",
+    "latency_series",
+    "glyphogram_series",
+    "glyph_top",
+]
+
+
+class MetricsVerbositySpec(NamedTuple):
+    """Runtime configuration for metrics verbosity tiers."""
+
+    name: str
+    enable_phase_sync: bool
+    enable_sigma: bool
+    enable_aggregate_si: bool
+    enable_advanced: bool
+    attach_coherence_hooks: bool
+    attach_diagnosis_hooks: bool
+
+
+METRICS_VERBOSITY_DEFAULT = TELEMETRY_VERBOSITY_DEFAULT
+
+_METRICS_VERBOSITY_PRESETS: dict[str, MetricsVerbositySpec] = {}
+
+
+def _register_metrics_preset(spec: MetricsVerbositySpec) -> None:
+    if spec.name not in TELEMETRY_VERBOSITY_LEVELS:
+        raise ValueError(
+            "Unknown metrics verbosity '%s'; use %s" % (
+                spec.name,
+                ", ".join(TELEMETRY_VERBOSITY_LEVELS),
+            )
+        )
+    _METRICS_VERBOSITY_PRESETS[spec.name] = spec
+
+
+_register_metrics_preset(
+    MetricsVerbositySpec(
+        name=TelemetryVerbosity.BASIC.value,
+        enable_phase_sync=False,
+        enable_sigma=False,
+        enable_aggregate_si=False,
+        enable_advanced=False,
+        attach_coherence_hooks=False,
+        attach_diagnosis_hooks=False,
+    )
+)
+
+_detailed_spec = MetricsVerbositySpec(
+    name=TelemetryVerbosity.DETAILED.value,
+    enable_phase_sync=True,
+    enable_sigma=True,
+    enable_aggregate_si=True,
+    enable_advanced=False,
+    attach_coherence_hooks=True,
+    attach_diagnosis_hooks=False,
+)
+_register_metrics_preset(_detailed_spec)
+_register_metrics_preset(
+    _detailed_spec._replace(
+        name=TelemetryVerbosity.DEBUG.value,
+        enable_advanced=True,
+        attach_diagnosis_hooks=True,
+    )
+)
+
+
+_METRICS_BASE_HISTORY_KEYS = ("C_steps", "stable_frac", "delta_Si", "B")
+_METRICS_PHASE_HISTORY_KEYS = ("phase_sync", "kuramoto_R")
+_METRICS_SIGMA_HISTORY_KEYS = (
+    GLYPH_LOAD_STABILIZERS_KEY,
+    "glyph_load_disr",
+    "sense_sigma_x",
+    "sense_sigma_y",
+    "sense_sigma_mag",
+    "sense_sigma_angle",
+)
+_METRICS_SI_HISTORY_KEYS = ("Si_mean", "Si_hi_frac", "Si_lo_frac")
+
+
+def _resolve_metrics_verbosity(cfg: Mapping[str, Any]) -> MetricsVerbositySpec:
+    """Return the preset matching ``cfg['verbosity']``."""
+
+    raw_value = cfg.get("verbosity", METRICS_VERBOSITY_DEFAULT)
+    key = str(raw_value).lower()
+    spec = _METRICS_VERBOSITY_PRESETS.get(key)
+    if spec is not None:
+        return spec
+    logger.warning(
+        "Unknown METRICS verbosity '%s'; falling back to '%s'",
+        raw_value,
+        METRICS_VERBOSITY_DEFAULT,
+    )
+    return _METRICS_VERBOSITY_PRESETS[METRICS_VERBOSITY_DEFAULT]
+
+
+def _metrics_step(G: TNFRGraph, ctx: dict[str, Any] | None = None) -> None:
+    """Update operational TNFR metrics per step."""
+
+    del ctx
+
+    cfg = cast(Mapping[str, Any], get_param(G, "METRICS"))
+    if not cfg.get("enabled", True):
+        return
+
+    spec = _resolve_metrics_verbosity(cfg)
+    hist = ensure_history(G)
+    if "glyph_load_estab" in hist:
+        raise ValueError(
+            "History payloads using 'glyph_load_estab' are no longer supported. "
+            "Rename the series to 'glyph_load_stabilizers' before loading the graph."
+        )
+    metrics_sentinel_key = "_metrics_history_id"
+    history_id = id(hist)
+    if G.graph.get(metrics_sentinel_key) != history_id:
+        for key in _METRICS_BASE_HISTORY_KEYS:
+            hist.setdefault(key, [])
+        if spec.enable_phase_sync:
+            for key in _METRICS_PHASE_HISTORY_KEYS:
+                hist.setdefault(key, [])
+        if spec.enable_sigma:
+            for key in _METRICS_SIGMA_HISTORY_KEYS:
+                hist.setdefault(key, [])
+        if spec.enable_aggregate_si:
+            for key in _METRICS_SI_HISTORY_KEYS:
+                hist.setdefault(key, [])
+        G.graph[metrics_sentinel_key] = history_id
+
+    dt = float(get_param(G, "DT"))
+    eps_dnfr = float(get_param(G, "EPS_DNFR_STABLE"))
+    eps_depi = float(get_param(G, "EPS_DEPI_STABLE"))
+    t = float(G.graph.get("_t", 0.0))
+
+    _update_coherence(G, hist)
+
+    raw_jobs = cfg.get("n_jobs")
+    metrics_jobs: int | None
+    try:
+        metrics_jobs = None if raw_jobs is None else int(raw_jobs)
+    except (TypeError, ValueError):
+        metrics_jobs = None
+    else:
+        if metrics_jobs <= 0:
+            metrics_jobs = None
+
+    _track_stability(
+        G,
+        hist,
+        dt,
+        eps_dnfr,
+        eps_depi,
+        n_jobs=metrics_jobs,
+    )
+    if spec.enable_phase_sync or spec.enable_sigma:
+        try:
+            if spec.enable_phase_sync:
+                _update_phase_sync(G, hist)
+            if spec.enable_sigma:
+                _update_sigma(G, hist)
+        except (KeyError, AttributeError, TypeError) as exc:
+            logger.debug("observer update failed: %s", exc)
+
+    if hist.get("C_steps") and hist.get("stable_frac"):
+        append_metric(
+            hist,
+            "iota",
+            hist["C_steps"][-1] * hist["stable_frac"][-1],
+        )
+
+    if spec.enable_aggregate_si:
+        _aggregate_si(G, hist, n_jobs=metrics_jobs)
+
+    if spec.enable_advanced:
+        _compute_advanced_metrics(
+            G,
+            cast(GlyphMetricsHistory, hist),
+            t,
+            dt,
+            cfg,
+            n_jobs=metrics_jobs,
+        )
+
+
+def register_metrics_callbacks(G: TNFRGraph) -> None:
+    cfg = cast(Mapping[str, Any], get_param(G, "METRICS"))
+    spec = _resolve_metrics_verbosity(cfg)
+    callback_manager.register_callback(
+        G,
+        event=CallbackEvent.AFTER_STEP.value,
+        func=_metrics_step,
+        name="metrics_step",
+    )
+    if spec.attach_coherence_hooks:
+        register_coherence_callbacks(G)
+    if spec.attach_diagnosis_hooks:
+        register_diagnosis_callbacks(G)

tnfr/metrics/core.pyi

@@ -0,0 +1,13 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+Tg_by_node: Any
+Tg_global: Any
+_metrics_step: Any
+glyph_top: Any
+glyphogram_series: Any
+latency_series: Any
+register_metrics_callbacks: Any