tnfr 4.5.2__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

@@ -6,17 +6,11 @@ from types import MappingProxyType
 from typing import Any, Iterable, Mapping, Sequence
 
 from ..alias import collect_attr, get_attr, multi_recompute_abs_max
-from ..collections_utils import normalize_weights
-from ..constants import DEFAULTS, get_aliases
-from ..cache import edge_version_cache
-from ..helpers.numeric import clamp01, kahan_sum_nd
-from ..import_utils import get_numpy
-from ..types import GraphLike
-
-ALIAS_DNFR = get_aliases("DNFR")
-ALIAS_D2EPI = get_aliases("D2EPI")
-ALIAS_DEPI = get_aliases("DEPI")
-ALIAS_VF = get_aliases("VF")
+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",
@@ -27,6 +21,7 @@ __all__ = (
     "merge_graph_weights",
     "merge_and_normalize_weights",
     "min_max_range",
+    "_coerce_jobs",
     "_get_vf_dnfr_max",
 )
 
@@ -72,7 +67,10 @@ def ensure_neighbors_map(G: GraphLike) -> Mapping[Any, Sequence[Any]]:
 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, {})}
+    overrides = G.graph.get(key, {})
+    if overrides is None or not isinstance(overrides, Mapping):
+        overrides = {}
+    return {**DEFAULTS[key], **overrides}
 
 
 def merge_and_normalize_weights(
@@ -103,7 +101,7 @@ def compute_dnfr_accel_max(G: GraphLike) -> dict[str, float]:
     )
 
 
-def normalize_dnfr(nd: Mapping[str, Any], max_val: float) -> float:
+def normalize_dnfr(nd: NodeAttrMap, max_val: float) -> float:
     """Normalise ``|ΔNFR|`` using ``max_val``."""
 
     if max_val <= 0:
@@ -137,9 +135,7 @@ def _get_vf_dnfr_max(G: GraphLike) -> tuple[float, float]:
     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}
-        )
+        maxes = multi_recompute_abs_max(G, {"_vfmax": ALIAS_VF, "_dnfrmax": ALIAS_DNFR})
         if vfmax is None:
             vfmax = maxes["_vfmax"]
         if dnfrmax is None:
@@ -149,3 +145,14 @@ def _get_vf_dnfr_max(G: GraphLike) -> tuple[float, float]:
     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

@@ -2,13 +2,34 @@
 
 from __future__ import annotations
 
-from typing import Any
+from collections.abc import Mapping, MutableMapping
+from typing import Any, NamedTuple, cast
 
-from ..callback_utils import CallbackEvent, callback_manager
+from ..utils import CallbackEvent, callback_manager
 from ..constants import get_param
 from ..glyph_history import append_metric, ensure_history
-from ..logging_utils import get_logger
+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,
@@ -17,18 +38,28 @@ from .coherence import (
     register_coherence_callbacks,
 )
 from .diagnosis import register_diagnosis_callbacks
-from .glyph_timing import _compute_advanced_metrics
+from .glyph_timing import GlyphMetricsHistory, _compute_advanced_metrics
 from .reporting import (
     Tg_by_node,
     Tg_global,
-    glyphogram_series,
     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",
@@ -39,32 +70,176 @@ __all__ = [
 ]
 
 
-def _metrics_step(G, ctx: dict[str, Any] | None = None):
+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 = get_param(G, "METRICS")
+    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 k in (
-            "C_steps",
-            "stable_frac",
-            "phase_sync",
-            "glyph_load_estab",
-            "glyph_load_disr",
-            "Si_mean",
-            "Si_hi_frac",
-            "Si_lo_frac",
-            "delta_Si",
-            "B",
-        ):
-            hist.setdefault(k, [])
+        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"))
@@ -73,29 +248,69 @@ def _metrics_step(G, ctx: dict[str, Any] | None = None):
     t = float(G.graph.get("_t", 0.0))
 
     _update_coherence(G, hist)
-    _track_stability(G, hist, dt, eps_dnfr, eps_depi)
+
+    raw_jobs = cfg.get("n_jobs")
+    metrics_jobs: int | None
     try:
-        _update_phase_sync(G, hist)
-        _update_sigma(G, hist)
-        if hist.get("C_steps") and hist.get("stable_frac"):
-            append_metric(
-                hist,
-                "iota",
-                hist["C_steps"][-1] * hist["stable_frac"][-1],
-            )
-    except (KeyError, AttributeError, TypeError) as exc:
-        logger.debug("observer update failed: %s", exc)
+        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,
+        )
 
-    _aggregate_si(G, hist)
-    _compute_advanced_metrics(G, hist, t, dt, cfg)
 
+def register_metrics_callbacks(G: TNFRGraph) -> None:
+    """Attach canonical metrics callbacks according to graph configuration."""
 
-def register_metrics_callbacks(G) -> 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",
     )
-    register_coherence_callbacks(G)
-    register_diagnosis_callbacks(G)
+    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