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

tnfr/metrics/coherence.pyi

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from .._compat import TypeAlias as TypeAlias
+from ..alias import (
+    collect_attr as collect_attr,
+    collect_theta_attr as collect_theta_attr,
+    get_attr as get_attr,
+    set_attr as set_attr,
+)
+from ..constants import get_param as get_param
+from ..constants.aliases import (
+    ALIAS_D2VF as ALIAS_D2VF,
+    ALIAS_DEPI as ALIAS_DEPI,
+    ALIAS_DNFR as ALIAS_DNFR,
+    ALIAS_DSI as ALIAS_DSI,
+    ALIAS_DVF as ALIAS_DVF,
+    ALIAS_EPI as ALIAS_EPI,
+    ALIAS_SI as ALIAS_SI,
+    ALIAS_VF as ALIAS_VF,
+)
+from ..glyph_history import (
+    append_metric as append_metric,
+    ensure_history as ensure_history,
+)
+from ..observers import (
+    DEFAULT_GLYPH_LOAD_SPAN as DEFAULT_GLYPH_LOAD_SPAN,
+    DEFAULT_WBAR_SPAN as DEFAULT_WBAR_SPAN,
+    glyph_load as glyph_load,
+    kuramoto_order as kuramoto_order,
+    phase_sync as phase_sync,
+)
+from ..sense import sigma_vector as sigma_vector
+from ..types import (
+    CoherenceMetric as CoherenceMetric,
+    FloatArray as FloatArray,
+    FloatMatrix as FloatMatrix,
+    GlyphLoadDistribution as GlyphLoadDistribution,
+    HistoryState as HistoryState,
+    NodeId as NodeId,
+    ParallelWijPayload as ParallelWijPayload,
+    SigmaVector as SigmaVector,
+    TNFRGraph as TNFRGraph,
+)
+from ..utils import (
+    CallbackEvent as CallbackEvent,
+    callback_manager as callback_manager,
+    clamp01 as clamp01,
+    ensure_node_index_map as ensure_node_index_map,
+    get_logger as get_logger,
+    get_numpy as get_numpy,
+    normalize_weights as normalize_weights,
+    resolve_chunk_size as resolve_chunk_size,
+)
+from .common import (
+    compute_coherence as compute_coherence,
+    min_max_range as min_max_range,
+)
+from .trig_cache import (
+    compute_theta_trig as compute_theta_trig,
+    get_trig_cache as get_trig_cache,
+)
+from _typeshed import Incomplete
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Any
+
+logger: Incomplete
+GLYPH_LOAD_STABILIZERS_KEY: str
+
+@dataclass
+class SimilarityInputs:
+    th_vals: Sequence[float]
+    epi_vals: Sequence[float]
+    vf_vals: Sequence[float]
+    si_vals: Sequence[float]
+    cos_vals: Sequence[float] | None = ...
+    sin_vals: Sequence[float] | None = ...
+
+CoherenceMatrixDense = list[list[float]]
+CoherenceMatrixSparse = list[tuple[int, int, float]]
+CoherenceMatrixPayload = CoherenceMatrixDense | CoherenceMatrixSparse
+PhaseSyncWeights: TypeAlias
+SimilarityComponents = tuple[float, float, float, float]
+VectorizedComponents: TypeAlias
+ScalarOrArray: TypeAlias
+StabilityChunkArgs = tuple[
+    Sequence[float],
+    Sequence[float],
+    Sequence[float],
+    Sequence[float | None],
+    Sequence[float],
+    Sequence[float | None],
+    Sequence[float | None],
+    float,
+    float,
+    float,
+]
+StabilityChunkResult = tuple[
+    int, int, float, float, list[float], list[float], list[float]
+]
+MetricValue: TypeAlias
+MetricProvider = Callable[[], MetricValue]
+MetricRecord: TypeAlias
+
+def compute_wij_phase_epi_vf_si(
+    inputs: SimilarityInputs,
+    i: int | None = None,
+    j: int | None = None,
+    *,
+    trig: Any | None = None,
+    G: TNFRGraph | None = None,
+    nodes: Sequence[NodeId] | None = None,
+    epi_range: float = 1.0,
+    vf_range: float = 1.0,
+    np: ModuleType | None = None,
+) -> SimilarityComponents | VectorizedComponents: ...
+def coherence_matrix(
+    G: TNFRGraph, use_numpy: bool | None = None, *, n_jobs: int | None = None
+) -> tuple[list[NodeId] | None, CoherenceMatrixPayload | None]: ...
+def local_phase_sync_weighted(
+    G: TNFRGraph,
+    n: NodeId,
+    nodes_order: Sequence[NodeId] | None = None,
+    W_row: PhaseSyncWeights | None = None,
+    node_to_index: Mapping[NodeId, int] | None = None,
+) -> float: ...
+def local_phase_sync(G: TNFRGraph, n: NodeId) -> float: ...
+def register_coherence_callbacks(G: TNFRGraph) -> None: ...

tnfr/metrics/common.py

@@ -0,0 +1,158 @@
+"""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
+from ..constants.aliases import ALIAS_D2EPI, ALIAS_DEPI, ALIAS_DNFR, ALIAS_VF
+from ..utils import clamp01, kahan_sum_nd, normalize_optional_int
+from ..types import GraphLike, NodeAttrMap
+from ..utils import edge_version_cache, get_numpy, normalize_weights
+
+__all__ = (
+    "GraphLike",
+    "compute_coherence",
+    "compute_dnfr_accel_max",
+    "normalize_dnfr",
+    "ensure_neighbors_map",
+    "merge_graph_weights",
+    "merge_and_normalize_weights",
+    "min_max_range",
+    "_coerce_jobs",
+    "_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."""
+
+    overrides = G.graph.get(key, {})
+    if overrides is None or not isinstance(overrides, Mapping):
+        overrides = {}
+    return {**DEFAULTS[key], **overrides}
+
+
+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: NodeAttrMap, 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)
+
+
+def _coerce_jobs(raw_jobs: Any | None) -> int | None:
+    """Normalise parallel job hints shared by metrics modules."""
+
+    return normalize_optional_int(
+        raw_jobs,
+        allow_non_positive=False,
+        strict=False,
+        sentinels=None,
+    )

tnfr/metrics/common.pyi

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any, Literal, overload
+
+from ..types import GraphLike, NodeAttrMap
+
+__all__: tuple[str, ...]
+
+def __getattr__(name: str) -> Any: ...
+@overload
+def compute_coherence(G: GraphLike, *, return_means: Literal[False] = ...) -> float: ...
+@overload
+def compute_coherence(
+    G: GraphLike, *, return_means: Literal[True]
+) -> tuple[float, float, float]: ...
+def compute_coherence(
+    G: GraphLike, *, return_means: bool = ...
+) -> float | tuple[float, float, float]: ...
+def ensure_neighbors_map(G: GraphLike) -> Mapping[Any, Sequence[Any]]: ...
+def merge_graph_weights(G: GraphLike, key: str) -> dict[str, float]: ...
+def merge_and_normalize_weights(
+    G: GraphLike,
+    key: str,
+    fields: Sequence[str],
+    *,
+    default: float = ...,
+) -> dict[str, float]: ...
+def compute_dnfr_accel_max(G: GraphLike) -> dict[str, float]: ...
+def normalize_dnfr(nd: NodeAttrMap, max_val: float) -> float: ...
+def min_max_range(
+    values: Iterable[float], *, default: tuple[float, float] = ...
+) -> tuple[float, float]: ...
+def _get_vf_dnfr_max(G: GraphLike) -> tuple[float, float]: ...
+def _coerce_jobs(raw_jobs: Any | None) -> int | None: ...

tnfr/metrics/core.py

@@ -0,0 +1,316 @@
+"""Basic metrics orchestrator."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from typing import Any, NamedTuple, cast
+
+from ..utils import CallbackEvent, callback_manager
+from ..constants import get_param
+from ..glyph_history import append_metric, ensure_history
+from ..telemetry import ensure_nu_f_telemetry
+from ..units import get_hz_bridge
+from ..telemetry.verbosity import (
+    TELEMETRY_VERBOSITY_DEFAULT,
+    TELEMETRY_VERBOSITY_LEVELS,
+    TelemetryVerbosity,
+)
+from ..types import (
+    GlyphSelector,
+    NodeId,
+    SelectorPreselectionChoices,
+    SelectorPreselectionMetrics,
+    SelectorPreselectionPayload,
+    TNFRGraph,
+    TraceCallback,
+    TraceFieldFn,
+    TraceFieldMap,
+    TraceFieldRegistry,
+)
+from ..utils import get_logger
+from .coherence import (
+    GLYPH_LOAD_STABILIZERS_KEY,
+    _aggregate_si,
+    _track_stability,
+    _update_coherence,
+    _update_phase_sync,
+    _update_sigma,
+    register_coherence_callbacks,
+)
+from .diagnosis import register_diagnosis_callbacks
+from .glyph_timing import GlyphMetricsHistory, _compute_advanced_metrics
+from .reporting import (
+    Tg_by_node,
+    Tg_global,
+    glyph_top,
+    glyphogram_series,
+    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
+    enable_nu_f: 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,
+        enable_nu_f=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,
+    enable_nu_f=True,
+)
+_register_metrics_preset(_detailed_spec)
+_register_metrics_preset(
+    _detailed_spec._replace(
+        name=TelemetryVerbosity.DEBUG.value,
+        enable_advanced=True,
+        attach_diagnosis_hooks=True,
+        enable_nu_f=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")
+_METRICS_NU_F_HISTORY_KEYS = (
+    "nu_f_rate_hz_str",
+    "nu_f_rate_hz",
+    "nu_f_ci_lower_hz_str",
+    "nu_f_ci_upper_hz_str",
+    "nu_f_ci_lower_hz",
+    "nu_f_ci_upper_hz",
+)
+
+
+def _update_nu_f_snapshot(
+    G: TNFRGraph,
+    hist: MutableMapping[str, Any],
+    *,
+    record_history: bool,
+) -> None:
+    """Refresh νf telemetry snapshot and optionally persist it in history."""
+
+    accumulator = ensure_nu_f_telemetry(G, confidence_level=None)
+    snapshot = accumulator.snapshot(graph=G)
+    payload = snapshot.as_payload()
+    bridge: float | None
+    try:
+        bridge = float(get_hz_bridge(G))
+    except (TypeError, ValueError, KeyError):
+        bridge = None
+    else:
+        payload["hz_bridge"] = bridge
+
+    telemetry = G.graph.setdefault("telemetry", {})
+    if not isinstance(telemetry, MutableMapping):
+        telemetry = {}
+        G.graph["telemetry"] = telemetry
+    telemetry["nu_f_snapshot"] = payload
+    telemetry["nu_f_bridge"] = bridge
+
+    if record_history:
+        append_metric(hist, "nu_f_rate_hz_str", snapshot.rate_hz_str)
+        append_metric(hist, "nu_f_rate_hz", snapshot.rate_hz)
+        append_metric(hist, "nu_f_ci_lower_hz_str", snapshot.ci_lower_hz_str)
+        append_metric(hist, "nu_f_ci_upper_hz_str", snapshot.ci_upper_hz_str)
+        append_metric(hist, "nu_f_ci_lower_hz", snapshot.ci_lower_hz)
+        append_metric(hist, "nu_f_ci_upper_hz", snapshot.ci_upper_hz)
+
+    G.graph["_nu_f_snapshot_payload"] = payload
+
+
+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, [])
+        if spec.enable_nu_f:
+            for key in _METRICS_NU_F_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)
+
+    _update_nu_f_snapshot(G, hist, record_history=spec.enable_nu_f)
+
+    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:
+    """Attach canonical metrics callbacks according to graph configuration."""
+
+    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