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

tnfr/metrics/common.py

@@ -0,0 +1,151 @@
+"""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 ..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")
+
+__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/core.py

@@ -0,0 +1,101 @@
+"""Basic metrics orchestrator."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..callback_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 .coherence import (
+    _aggregate_si,
+    _track_stability,
+    _update_coherence,
+    _update_phase_sync,
+    _update_sigma,
+    register_coherence_callbacks,
+)
+from .diagnosis import register_diagnosis_callbacks
+from .glyph_timing import _compute_advanced_metrics
+from .reporting import (
+    Tg_by_node,
+    Tg_global,
+    glyphogram_series,
+    glyph_top,
+    latency_series,
+)
+
+logger = get_logger(__name__)
+
+__all__ = [
+    "_metrics_step",
+    "register_metrics_callbacks",
+    "Tg_global",
+    "Tg_by_node",
+    "latency_series",
+    "glyphogram_series",
+    "glyph_top",
+]
+
+
+def _metrics_step(G, ctx: dict[str, Any] | None = None):
+    """Update operational TNFR metrics per step."""
+
+    del ctx
+
+    cfg = get_param(G, "METRICS")
+    if not cfg.get("enabled", True):
+        return
+
+    hist = ensure_history(G)
+    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, [])
+        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)
+    _track_stability(G, hist, dt, eps_dnfr, eps_depi)
+    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)
+
+    _aggregate_si(G, hist)
+    _compute_advanced_metrics(G, hist, t, dt, cfg)
+
+
+def register_metrics_callbacks(G) -> None:
+    callback_manager.register_callback(
+        G,
+        event=CallbackEvent.AFTER_STEP.value,
+        func=_metrics_step,
+        name="metrics_step",
+    )
+    register_coherence_callbacks(G)
+    register_diagnosis_callbacks(G)

tnfr/metrics/diagnosis.py

@@ -0,0 +1,234 @@
+"""Diagnostic metrics."""
+
+from __future__ import annotations
+
+from statistics import fmean, StatisticsError
+from operator import ge, le
+from typing import Any
+
+from ..constants import (
+    VF_KEY,
+    get_aliases,
+    get_param,
+)
+from ..callback_utils import CallbackEvent, callback_manager
+from ..glyph_history import ensure_history, append_metric
+from ..alias import get_attr
+from ..helpers.numeric import clamp01, similarity_abs
+from .common import compute_dnfr_accel_max, min_max_range, normalize_dnfr
+from .coherence import (
+    local_phase_sync,
+    local_phase_sync_weighted,
+)
+
+ALIAS_EPI = get_aliases("EPI")
+ALIAS_VF = get_aliases("VF")
+ALIAS_SI = get_aliases("SI")
+
+def _symmetry_index(
+    G, n, epi_min: float | None = None, epi_max: float | None = None
+):
+    """Compute the symmetry index for node ``n`` based on EPI values."""
+    nd = G.nodes[n]
+    epi_i = get_attr(nd, ALIAS_EPI, 0.0)
+    vec = G.neighbors(n)
+    try:
+        epi_bar = fmean(get_attr(G.nodes[v], ALIAS_EPI, epi_i) for v in vec)
+    except StatisticsError:
+        return 1.0
+    if epi_min is None or epi_max is None:
+        epi_iter = (get_attr(G.nodes[v], ALIAS_EPI, 0.0) for v in G.nodes())
+        epi_min, epi_max = min_max_range(epi_iter, default=(0.0, 1.0))
+    return similarity_abs(epi_i, epi_bar, epi_min, epi_max)
+
+
+def _state_from_thresholds(Rloc, dnfr_n, cfg):
+    stb = cfg.get("stable", {"Rloc_hi": 0.8, "dnfr_lo": 0.2, "persist": 3})
+    dsr = cfg.get("dissonance", {"Rloc_lo": 0.4, "dnfr_hi": 0.5, "persist": 3})
+
+    stable_checks = {
+        "Rloc": (Rloc, float(stb["Rloc_hi"]), ge),
+        "dnfr": (dnfr_n, float(stb["dnfr_lo"]), le),
+    }
+    if all(comp(val, thr) for val, thr, comp in stable_checks.values()):
+        return "estable"
+
+    dissonant_checks = {
+        "Rloc": (Rloc, float(dsr["Rloc_lo"]), le),
+        "dnfr": (dnfr_n, float(dsr["dnfr_hi"]), ge),
+    }
+    if all(comp(val, thr) for val, thr, comp in dissonant_checks.values()):
+        return "disonante"
+
+    return "transicion"
+
+
+def _recommendation(state, cfg):
+    adv = cfg.get("advice", {})
+    key = {
+        "estable": "stable",
+        "transicion": "transition",
+        "disonante": "dissonant",
+    }[state]
+    return list(adv.get(key, []))
+
+
+def _get_last_weights(G, hist):
+    """Return last Wi and Wm matrices from history."""
+    CfgW = get_param(G, "COHERENCE")
+    Wkey = CfgW.get("Wi_history_key", "W_i")
+    Wm_key = CfgW.get("history_key", "W_sparse")
+    Wi_series = hist.get(Wkey, [])
+    Wm_series = hist.get(Wm_key, [])
+    Wi_last = Wi_series[-1] if Wi_series else None
+    Wm_last = Wm_series[-1] if Wm_series else None
+    return Wi_last, Wm_last
+
+
+def _node_diagnostics(
+    G,
+    n,
+    i,
+    nodes,
+    node_to_index,
+    Wi_last,
+    Wm_last,
+    epi_min,
+    epi_max,
+    dnfr_max,
+    dcfg,
+):
+    nd = G.nodes[n]
+    Si = clamp01(get_attr(nd, ALIAS_SI, 0.0))
+    EPI = get_attr(nd, ALIAS_EPI, 0.0)
+    vf = get_attr(nd, ALIAS_VF, 0.0)
+    dnfr_n = normalize_dnfr(nd, dnfr_max)
+
+    if Wm_last is not None:
+        if Wm_last and isinstance(Wm_last[0], list):
+            row = Wm_last[i]
+        else:
+            row = Wm_last
+        Rloc = local_phase_sync_weighted(
+            G, n, nodes_order=nodes, W_row=row, node_to_index=node_to_index
+        )
+    else:
+        Rloc = local_phase_sync(G, n)
+
+    symm = (
+        _symmetry_index(G, n, epi_min=epi_min, epi_max=epi_max)
+        if dcfg.get("compute_symmetry", True)
+        else None
+    )
+    state = _state_from_thresholds(Rloc, dnfr_n, dcfg)
+
+    alerts = []
+    if state == "disonante" and dnfr_n >= float(
+        dcfg.get("dissonance", {}).get("dnfr_hi", 0.5)
+    ):
+        alerts.append("high structural tension")
+
+    advice = _recommendation(state, dcfg)
+
+    return {
+        "node": n,
+        "Si": Si,
+        "EPI": EPI,
+        VF_KEY: vf,
+        "dnfr_norm": dnfr_n,
+        "W_i": (Wi_last[i] if (Wi_last and i < len(Wi_last)) else None),
+        "R_local": Rloc,
+        "symmetry": symm,
+        "state": state,
+        "advice": advice,
+        "alerts": alerts,
+    }
+
+
+def _diagnosis_step(G, ctx: dict[str, Any] | None = None):
+    del ctx
+
+    dcfg = get_param(G, "DIAGNOSIS")
+    if not dcfg.get("enabled", True):
+        return
+
+    hist = ensure_history(G)
+    key = dcfg.get("history_key", "nodal_diag")
+
+    norms = compute_dnfr_accel_max(G)
+    G.graph["_sel_norms"] = norms
+    dnfr_max = float(norms.get("dnfr_max", 1.0)) or 1.0
+    epi_iter = (get_attr(nd, ALIAS_EPI, 0.0) for _, nd in G.nodes(data=True))
+    epi_min, epi_max = min_max_range(epi_iter, default=(0.0, 1.0))
+
+    Wi_last, Wm_last = _get_last_weights(G, hist)
+
+    nodes = list(G.nodes())
+    node_to_index = {v: i for i, v in enumerate(nodes)}
+    diag = {}
+    for i, n in enumerate(nodes):
+        diag[n] = _node_diagnostics(
+            G,
+            n,
+            i,
+            nodes,
+            node_to_index,
+            Wi_last,
+            Wm_last,
+            epi_min,
+            epi_max,
+            dnfr_max,
+            dcfg,
+        )
+
+    append_metric(hist, key, diag)
+
+
+def dissonance_events(G, ctx: dict[str, Any] | None = None):
+    """Emit per-node structural dissonance start/end events.
+
+    Events are recorded as ``"dissonance_start"`` and ``"dissonance_end"``.
+    """
+
+    del ctx
+
+    hist = ensure_history(G)
+    # eventos de disonancia se registran en ``history['events']``
+    norms = G.graph.get("_sel_norms", {})
+    dnfr_max = float(norms.get("dnfr_max", 1.0)) or 1.0
+    step_idx = len(hist.get("C_steps", []))
+    nodes = list(G.nodes())
+    for n in nodes:
+        nd = G.nodes[n]
+        dn = normalize_dnfr(nd, dnfr_max)
+        Rloc = local_phase_sync(G, n)
+        st = bool(nd.get("_disr_state", False))
+        if (not st) and dn >= 0.5 and Rloc <= 0.4:
+            nd["_disr_state"] = True
+            append_metric(
+                hist,
+                "events",
+                ("dissonance_start", {"node": n, "step": step_idx}),
+            )
+        elif st and dn <= 0.2 and Rloc >= 0.7:
+            nd["_disr_state"] = False
+            append_metric(
+                hist,
+                "events",
+                ("dissonance_end", {"node": n, "step": step_idx}),
+            )
+
+
+def register_diagnosis_callbacks(G) -> None:
+    callback_manager.register_callback(
+        G,
+        event=CallbackEvent.AFTER_STEP.value,
+        func=_diagnosis_step,
+        name="diagnosis_step",
+    )
+    callback_manager.register_callback(
+        G,
+        event=CallbackEvent.AFTER_STEP.value,
+        func=dissonance_events,
+        name="dissonance_events",
+    )

tnfr/metrics/export.py

@@ -0,0 +1,137 @@
+"""Metrics export."""
+
+from __future__ import annotations
+
+import csv
+import math
+from itertools import zip_longest, tee
+
+from ..glyph_history import ensure_history
+from ..io import safe_write
+from ..constants_glyphs import GLYPHS_CANONICAL
+from .core import glyphogram_series
+from ..json_utils import json_dumps
+
+
+def _write_csv(path, headers, rows):
+    def _write(f):
+        writer = csv.writer(f)
+        writer.writerow(headers)
+        for row in rows:
+            writer.writerow(row)
+
+    safe_write(path, _write, newline="")
+
+
+def _iter_glif_rows(glyph):
+    ts = glyph.get("t", [])
+    # Precompute columns for each glyph to avoid repeated lookups.
+    # ``default_col`` is shared by reference for missing glyphs to prevent
+    # unnecessary list allocations.
+    default_col = [0] * len(ts)
+    cols = [glyph.get(g, default_col) for g in GLYPHS_CANONICAL]
+    for i, t in enumerate(ts):
+        yield [t] + [col[i] for col in cols]
+
+
+def export_metrics(G, base_path: str, fmt: str = "csv") -> None:
+    """Dump glyphogram and σ(t) trace to compact CSV or JSON files."""
+    hist = ensure_history(G)
+    glyph = glyphogram_series(G)
+    sigma_x = hist.get("sense_sigma_x", [])
+    sigma_y = hist.get("sense_sigma_y", [])
+    sigma_mag = hist.get("sense_sigma_mag", [])
+    sigma_angle = hist.get("sense_sigma_angle", [])
+    t_series = hist.get("sense_sigma_t", []) or glyph.get("t", [])
+    rows_raw = zip_longest(
+        t_series, sigma_x, sigma_y, sigma_mag, sigma_angle, fillvalue=None
+    )
+
+    def _clean(value: float | None) -> float:
+        """Return ``0`` for ``None`` or ``NaN`` values."""
+        if value is None or (isinstance(value, float) and math.isnan(value)):
+            return 0
+        return value
+
+    def _gen_rows():
+        for i, (t, x, y, m, a) in enumerate(rows_raw):
+            yield (
+                i if t is None else t,
+                _clean(x),
+                _clean(y),
+                _clean(m),
+                _clean(a),
+            )
+
+    rows_csv, rows_sigma = tee(_gen_rows())
+
+    sigma: dict[str, list[float]] = {
+        "t": [],
+        "sigma_x": [],
+        "sigma_y": [],
+        "mag": [],
+        "angle": [],
+    }
+    for t, x, y, m, a in rows_sigma:
+        sigma["t"].append(t)
+        sigma["sigma_x"].append(x)
+        sigma["sigma_y"].append(y)
+        sigma["mag"].append(m)
+        sigma["angle"].append(a)
+    morph = hist.get("morph", [])
+    epi_supp = hist.get("EPI_support", [])
+    fmt = fmt.lower()
+    if fmt not in {"csv", "json"}:
+        raise ValueError(f"Formato de exportación no soportado: {fmt}")
+    if fmt == "csv":
+        specs = [
+            (
+                "_glyphogram.csv",
+                ["t", *GLYPHS_CANONICAL],
+                _iter_glif_rows(glyph),
+            ),
+            (
+                "_sigma.csv",
+                ["t", "x", "y", "mag", "angle"],
+                ([t, x, y, m, a] for t, x, y, m, a in rows_csv),
+            ),
+        ]
+        if morph:
+            specs.append(
+                (
+                    "_morph.csv",
+                    ["t", "ID", "CM", "NE", "PP"],
+                    (
+                        [
+                            row.get("t"),
+                            row.get("ID"),
+                            row.get("CM"),
+                            row.get("NE"),
+                            row.get("PP"),
+                        ]
+                        for row in morph
+                    ),
+                )
+            )
+        if epi_supp:
+            specs.append(
+                (
+                    "_epi_support.csv",
+                    ["t", "size", "epi_norm"],
+                    (
+                        [row.get("t"), row.get("size"), row.get("epi_norm")]
+                        for row in epi_supp
+                    ),
+                )
+            )
+        for suffix, headers, rows in specs:
+            _write_csv(base_path + suffix, headers, rows)
+    else:
+        data = {
+            "glyphogram": glyph,
+            "sigma": sigma,
+            "morph": morph,
+            "epi_support": epi_supp,
+        }
+        json_path = base_path + ".json"
+        safe_write(json_path, lambda f: f.write(json_dumps(data)))