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

tnfr/metrics/diagnosis.pyi

@@ -0,0 +1,89 @@
+from typing import Any, Mapping, Sequence
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ALIAS_DNFR: Any
+ALIAS_EPI: Any
+ALIAS_SI: Any
+ALIAS_VF: Any
+CallbackEvent: Any
+CoherenceMatrixPayload: Any
+Iterable: Any
+ProcessPoolExecutor: Any
+StatisticsError: Any
+TNFRGraph: Any
+TRANSITION: Any
+VF_KEY: Any
+annotations: Any
+append_metric: Any
+callback_manager: Any
+clamp01: Any
+coherence_matrix: Any
+compute_dnfr_accel_max: Any
+compute_theta_trig: Any
+dissonance_events: Any
+ensure_history: Any
+fmean: Any
+ge: Any
+get_aliases: Any
+get_attr: Any
+get_numpy: Any
+get_param: Any
+get_trig_cache: Any
+le: Any
+local_phase_sync: Any
+math: Any
+min_max_range: Any
+normalize_dnfr: Any
+partial: Any
+register_diagnosis_callbacks: Any
+similarity_abs: Any
+
+class RLocalWorkerArgs:
+    chunk: Sequence[Any]
+    coherence_nodes: Sequence[Any]
+    weight_matrix: Any
+    weight_index: Mapping[Any, int]
+    neighbors_map: Mapping[Any, tuple[Any, ...]]
+    cos_map: Mapping[Any, float]
+    sin_map: Mapping[Any, float]
+
+    def __init__(
+        self,
+        chunk: Sequence[Any],
+        coherence_nodes: Sequence[Any],
+        weight_matrix: Any,
+        weight_index: Mapping[Any, int],
+        neighbors_map: Mapping[Any, tuple[Any, ...]],
+        cos_map: Mapping[Any, float],
+        sin_map: Mapping[Any, float],
+    ) -> None: ...
+
+
+class NeighborMeanWorkerArgs:
+    chunk: Sequence[Any]
+    neighbors_map: Mapping[Any, tuple[Any, ...]]
+    epi_map: Mapping[Any, float]
+
+    def __init__(
+        self,
+        chunk: Sequence[Any],
+        neighbors_map: Mapping[Any, tuple[Any, ...]],
+        epi_map: Mapping[Any, float],
+    ) -> None: ...
+
+
+def _rlocal_worker(args: RLocalWorkerArgs) -> list[float]: ...
+
+def _neighbor_mean_worker(args: NeighborMeanWorkerArgs) -> list[float | None]: ...
+
+def _state_from_thresholds(Rloc: float, dnfr_n: float, cfg: Mapping[str, Any]) -> str: ...
+
+def _recommendation(state: str, cfg: Mapping[str, Any]) -> list[Any]: ...
+
+def _get_last_weights(
+    G: TNFRGraph,
+    hist: Mapping[str, Sequence[CoherenceMatrixPayload | None]],
+) -> tuple[CoherenceMatrixPayload | None, CoherenceMatrixPayload | None]: ...

tnfr/metrics/export.py

@@ -4,17 +4,25 @@ from __future__ import annotations
 
 import csv
 import math
+from collections.abc import Iterable, Iterator, Sequence
 from itertools import zip_longest, tee
+from typing import Mapping, TextIO
 
+from ..config.constants import GLYPHS_CANONICAL
 from ..glyph_history import ensure_history
 from ..io import safe_write
-from ..constants_glyphs import GLYPHS_CANONICAL
+from ..utils import json_dumps
+from ..types import Graph
 from .core import glyphogram_series
-from ..json_utils import json_dumps
+from .glyph_timing import SigmaTrace
 
 
-def _write_csv(path, headers, rows):
-    def _write(f):
+def _write_csv(
+    path: str,
+    headers: Sequence[str],
+    rows: Iterable[Sequence[object]],
+) -> None:
+    def _write(f: TextIO) -> None:
         writer = csv.writer(f)
         writer.writerow(headers)
         for row in rows:
@@ -23,7 +31,9 @@ def _write_csv(path, headers, rows):
     safe_write(path, _write, newline="")
 
 
-def _iter_glif_rows(glyph):
+def _iter_glif_rows(
+    glyph: Mapping[str, Sequence[float]],
+) -> Iterator[list[float]]:
     ts = glyph.get("t", [])
     # Precompute columns for each glyph to avoid repeated lookups.
     # ``default_col`` is shared by reference for missing glyphs to prevent
@@ -34,7 +44,7 @@ def _iter_glif_rows(glyph):
         yield [t] + [col[i] for col in cols]
 
 
-def export_metrics(G, base_path: str, fmt: str = "csv") -> None:
+def export_metrics(G: Graph, 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)
@@ -53,7 +63,7 @@ def export_metrics(G, base_path: str, fmt: str = "csv") -> None:
             return 0
         return value
 
-    def _gen_rows():
+    def _gen_rows() -> Iterator[tuple[float, float, float, float, float]]:
         for i, (t, x, y, m, a) in enumerate(rows_raw):
             yield (
                 i if t is None else t,
@@ -65,7 +75,7 @@ def export_metrics(G, base_path: str, fmt: str = "csv") -> None:
 
     rows_csv, rows_sigma = tee(_gen_rows())
 
-    sigma: dict[str, list[float]] = {
+    sigma: SigmaTrace = {
         "t": [],
         "sigma_x": [],
         "sigma_y": [],
@@ -78,13 +88,13 @@ def export_metrics(G, base_path: str, fmt: str = "csv") -> None:
         sigma["sigma_y"].append(y)
         sigma["mag"].append(m)
         sigma["angle"].append(a)
-    morph = hist.get("morph", [])
-    epi_supp = hist.get("EPI_support", [])
+    morph: Sequence[Mapping[str, float]] = hist.get("morph", [])
+    epi_supp: Sequence[Mapping[str, float]] = hist.get("EPI_support", [])
     fmt = fmt.lower()
     if fmt not in {"csv", "json"}:
-        raise ValueError(f"Formato de exportación no soportado: {fmt}")
+        raise ValueError(f"Unsupported export format: {fmt}")
     if fmt == "csv":
-        specs = [
+        specs: list[tuple[str, Sequence[str], Iterable[Sequence[object]]]] = [
             (
                 "_glyphogram.csv",
                 ["t", *GLYPHS_CANONICAL],
@@ -134,4 +144,8 @@ def export_metrics(G, base_path: str, fmt: str = "csv") -> None:
             "epi_support": epi_supp,
         }
         json_path = base_path + ".json"
-        safe_write(json_path, lambda f: f.write(json_dumps(data)))
+
+        def _write_json(f: TextIO) -> None:
+            f.write(json_dumps(data))
+
+        safe_write(json_path, _write_json)

tnfr/metrics/glyph_timing.py

@@ -3,20 +3,70 @@
 from __future__ import annotations
 
 from collections import Counter, defaultdict
+from concurrent.futures import ProcessPoolExecutor
 from dataclasses import dataclass
-from typing import Any, Callable
+import math
+from types import ModuleType
+from typing import Any, Callable, Mapping, MutableMapping, MutableSequence, Sequence, TypedDict, cast
 
 from ..alias import get_attr
 from ..constants import get_aliases, get_param
-from ..constants_glyphs import GLYPH_GROUPS, GLYPHS_CANONICAL
+from ..config.constants import GLYPH_GROUPS, GLYPHS_CANONICAL
 from ..glyph_history import append_metric, last_glyph
-from ..types import Glyph
+from ..types import GraphLike
 
 ALIAS_EPI = get_aliases("EPI")
 
-LATENT_GLYPH = Glyph.SHA.value
+LATENT_GLYPH: str = "SHA"
 DEFAULT_EPI_SUPPORT_LIMIT = 0.05
 
+try:  # pragma: no cover - import guard exercised via tests
+    import numpy as _np  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover - numpy optional dependency
+    _np = None
+
+np: ModuleType | None = cast(ModuleType | None, _np)
+
+
+def _has_numpy_support(np_obj: object) -> bool:
+    """Return ``True`` when ``np_obj`` exposes the required NumPy API."""
+
+    return isinstance(np_obj, ModuleType) or (
+        np_obj is not None
+        and hasattr(np_obj, "fromiter")
+        and hasattr(np_obj, "bincount")
+    )
+
+
+class SigmaTrace(TypedDict):
+    """Time-aligned σ(t) trace exported alongside glyphograms."""
+
+    t: list[float]
+    sigma_x: list[float]
+    sigma_y: list[float]
+    mag: list[float]
+    angle: list[float]
+
+
+GlyphogramRow = MutableMapping[str, float]
+GlyphTimingTotals = MutableMapping[str, float]
+GlyphTimingByNode = MutableMapping[Any, MutableMapping[str, MutableSequence[float]]]
+GlyphCounts = Mapping[str, int]
+GlyphMetricsHistoryValue = MutableMapping[Any, Any] | MutableSequence[Any]
+GlyphMetricsHistory = MutableMapping[str, GlyphMetricsHistoryValue]
+MetricsListHistory = MutableMapping[str, list[Any]]
+
+_GLYPH_TO_INDEX = {glyph: idx for idx, glyph in enumerate(GLYPHS_CANONICAL)}
+
+
+def _coerce_float(value: Any) -> float:
+    """Attempt to coerce ``value`` to ``float`` returning ``0.0`` on failure."""
+
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
 
 @dataclass
 class GlyphTiming:
@@ -27,6 +77,10 @@ class GlyphTiming:
 __all__ = [
     "LATENT_GLYPH",
     "GlyphTiming",
+    "SigmaTrace",
+    "GlyphogramRow",
+    "GlyphTimingTotals",
+    "GlyphTimingByNode",
     "_tg_state",
     "for_each_glyph",
     "_update_tg_node",
@@ -44,13 +98,34 @@ __all__ = [
 # ---------------------------------------------------------------------------
 
 
-def _tg_state(nd: dict[str, Any]) -> GlyphTiming:
+def _count_glyphs_chunk(chunk: Sequence[str]) -> Counter[str]:
+    """Count glyph occurrences within a chunk (multiprocessing helper)."""
+
+    counter: Counter[str] = Counter()
+    for glyph in chunk:
+        counter[glyph] += 1
+    return counter
+
+
+def _epi_support_chunk(values: Sequence[float], threshold: float) -> tuple[float, int]:
+    """Compute EPI support contribution for a chunk."""
+
+    total = 0.0
+    count = 0
+    for value in values:
+        if value >= threshold:
+            total += value
+            count += 1
+    return total, count
+
+
+def _tg_state(nd: MutableMapping[str, Any]) -> GlyphTiming:
     """Expose per-node glyph timing state."""
 
     return nd.setdefault("_Tg", GlyphTiming())
 
 
-def for_each_glyph(fn: Callable[[str], Any]) -> None:
+def for_each_glyph(fn: Callable[[str], None]) -> None:
     """Apply ``fn`` to each canonical structural operator."""
 
     for g in GLYPHS_CANONICAL:
@@ -62,7 +137,13 @@ def for_each_glyph(fn: Callable[[str], Any]) -> None:
 # ---------------------------------------------------------------------------
 
 
-def _update_tg_node(n, nd, dt, tg_total, tg_by_node):
+def _update_tg_node(
+    n: Any,
+    nd: MutableMapping[str, Any],
+    dt: float,
+    tg_total: GlyphTimingTotals,
+    tg_by_node: GlyphTimingByNode | None,
+) -> tuple[str | None, bool]:
     """Track a node's glyph transition and accumulate run time."""
 
     g = last_glyph(nd)
@@ -85,19 +166,31 @@ def _update_tg_node(n, nd, dt, tg_total, tg_by_node):
     return g, g == LATENT_GLYPH
 
 
-def _update_tg(G, hist, dt, save_by_node: bool):
+def _update_tg(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    dt: float,
+    save_by_node: bool,
+    n_jobs: int | None = None,
+) -> tuple[Counter[str], int, int]:
     """Accumulate glyph dwell times for the entire graph."""
 
-    counts = Counter()
-    tg_total = hist.setdefault("Tg_total", defaultdict(float))
+    tg_total = cast(GlyphTimingTotals, hist.setdefault("Tg_total", defaultdict(float)))
     tg_by_node = (
-        hist.setdefault("Tg_by_node", defaultdict(lambda: defaultdict(list)))
+        cast(
+            GlyphTimingByNode,
+            hist.setdefault(
+                "Tg_by_node",
+                defaultdict(lambda: defaultdict(list)),
+            ),
+        )
         if save_by_node
         else None
     )
 
     n_total = 0
     n_latent = 0
+    glyph_sequence: list[str] = []
     for n, nd in G.nodes(data=True):
         g, is_latent = _update_tg_node(n, nd, dt, tg_total, tg_by_node)
         if g is None:
@@ -105,56 +198,142 @@ def _update_tg(G, hist, dt, save_by_node: bool):
         n_total += 1
         if is_latent:
             n_latent += 1
-        counts[g] += 1
+        glyph_sequence.append(g)
+
+    counts: Counter[str] = Counter()
+    if not glyph_sequence:
+        return counts, n_total, n_latent
+
+    if _has_numpy_support(np):
+        glyph_idx = np.fromiter(
+            (_GLYPH_TO_INDEX[glyph] for glyph in glyph_sequence),
+            dtype=np.int64,
+            count=len(glyph_sequence),
+        )
+        freq = np.bincount(glyph_idx, minlength=len(GLYPHS_CANONICAL))
+        counts.update(
+            {
+                glyph: int(freq[_GLYPH_TO_INDEX[glyph]])
+                for glyph in GLYPHS_CANONICAL
+                if freq[_GLYPH_TO_INDEX[glyph]]
+            }
+        )
+    elif n_jobs is not None and n_jobs > 1 and len(glyph_sequence) > 1:
+        chunk_size = max(1, math.ceil(len(glyph_sequence) / n_jobs))
+        futures = []
+        with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+            for start in range(0, len(glyph_sequence), chunk_size):
+                chunk = glyph_sequence[start:start + chunk_size]
+                futures.append(executor.submit(_count_glyphs_chunk, chunk))
+            for future in futures:
+                counts.update(future.result())
+    else:
+        counts.update(glyph_sequence)
+
     return counts, n_total, n_latent
 
 
-def _update_glyphogram(G, hist, counts, t, n_total):
+def _update_glyphogram(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    counts: GlyphCounts,
+    t: float,
+    n_total: int,
+) -> None:
     """Record glyphogram row from glyph counts."""
 
     normalize_series = bool(get_param(G, "METRICS").get("normalize_series", False))
-    row = {"t": t}
+    row: GlyphogramRow = {"t": t}
     total = max(1, n_total)
     for g in GLYPHS_CANONICAL:
         c = counts.get(g, 0)
         row[g] = (c / total) if normalize_series else c
-    append_metric(hist, "glyphogram", row)
+    append_metric(cast(MetricsListHistory, hist), "glyphogram", row)
 
 
-def _update_latency_index(G, hist, n_total, n_latent, t):
+def _update_latency_index(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    n_total: int,
+    n_latent: int,
+    t: float,
+) -> None:
     """Record latency index for the current step."""
 
     li = n_latent / max(1, n_total)
-    append_metric(hist, "latency_index", {"t": t, "value": li})
+    append_metric(
+        cast(MetricsListHistory, hist),
+        "latency_index",
+        {"t": t, "value": li},
+    )
 
 
 def _update_epi_support(
-    G,
-    hist,
-    t,
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    t: float,
     threshold: float = DEFAULT_EPI_SUPPORT_LIMIT,
-):
+    n_jobs: int | None = None,
+) -> None:
     """Measure EPI support and normalized magnitude."""
 
+    node_count = G.number_of_nodes()
     total = 0.0
     count = 0
-    for _, nd in G.nodes(data=True):
-        epi_val = abs(get_attr(nd, ALIAS_EPI, 0.0))
-        if epi_val >= threshold:
-            total += epi_val
-            count += 1
+
+    if _has_numpy_support(np) and node_count:
+        epi_values = np.fromiter(
+            (
+                abs(_coerce_float(get_attr(nd, ALIAS_EPI, 0.0)))
+                for _, nd in G.nodes(data=True)
+            ),
+            dtype=float,
+            count=node_count,
+        )
+        mask = epi_values >= threshold
+        count = int(mask.sum())
+        if count:
+            total = float(epi_values[mask].sum())
+    elif n_jobs is not None and n_jobs > 1 and node_count > 1:
+        values = [
+            abs(_coerce_float(get_attr(nd, ALIAS_EPI, 0.0)))
+            for _, nd in G.nodes(data=True)
+        ]
+        chunk_size = max(1, math.ceil(len(values) / n_jobs))
+        totals: list[tuple[float, int]] = []
+        with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+            futures = []
+            for start in range(0, len(values), chunk_size):
+                chunk = values[start:start + chunk_size]
+                futures.append(executor.submit(_epi_support_chunk, chunk, threshold))
+            for future in futures:
+                totals.append(future.result())
+        for part_total, part_count in totals:
+            total += part_total
+            count += part_count
+    else:
+        for _, nd in G.nodes(data=True):
+            epi_val = abs(_coerce_float(get_attr(nd, ALIAS_EPI, 0.0)))
+            if epi_val >= threshold:
+                total += epi_val
+                count += 1
     epi_norm = (total / count) if count else 0.0
     append_metric(
-        hist,
+        cast(MetricsListHistory, hist),
         "EPI_support",
         {"t": t, "size": count, "epi_norm": float(epi_norm)},
     )
 
 
-def _update_morph_metrics(G, hist, counts, t):
+def _update_morph_metrics(
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    counts: GlyphCounts,
+    t: float,
+) -> None:
     """Capture morphosyntactic distribution of glyphs."""
 
-    def get_count(keys):
+    def get_count(keys: Sequence[str]) -> int:
         return sum(counts.get(k, 0) for k in keys)
 
     total = max(1, sum(counts.values()))
@@ -165,25 +344,26 @@ def _update_morph_metrics(G, hist, counts, t):
     den = get_count(GLYPH_GROUPS.get("PP_den", ()))
     pp_val = 0.0 if den == 0 else num / den
     append_metric(
-        hist,
+        cast(MetricsListHistory, hist),
         "morph",
         {"t": t, "ID": id_val, "CM": cm_val, "NE": ne_val, "PP": pp_val},
     )
 
 
 def _compute_advanced_metrics(
-    G,
-    hist,
-    t,
-    dt,
-    cfg,
+    G: GraphLike,
+    hist: GlyphMetricsHistory,
+    t: float,
+    dt: float,
+    cfg: Mapping[str, Any],
     threshold: float = DEFAULT_EPI_SUPPORT_LIMIT,
-):
+    n_jobs: int | None = None,
+) -> None:
     """Compute glyph timing derived metrics."""
 
     save_by_node = bool(cfg.get("save_by_node", True))
-    counts, n_total, n_latent = _update_tg(G, hist, dt, save_by_node)
+    counts, n_total, n_latent = _update_tg(G, hist, dt, save_by_node, n_jobs=n_jobs)
     _update_glyphogram(G, hist, counts, t, n_total)
     _update_latency_index(G, hist, n_total, n_latent, t)
-    _update_epi_support(G, hist, t, threshold)
+    _update_epi_support(G, hist, t, threshold, n_jobs=n_jobs)
     _update_morph_metrics(G, hist, counts, t)

tnfr/metrics/reporting.py

@@ -2,12 +2,14 @@
 
 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
 
@@ -26,7 +28,7 @@ __all__ = [
 # ---------------------------------------------------------------------------
 
 
-def Tg_global(G, normalize: bool = True) -> dict[str, float]:
+def Tg_global(G: TNFRGraph, normalize: bool = True) -> dict[str, float]:
     """Total glyph dwell time per class."""
 
     hist = ensure_history(G)
@@ -34,7 +36,7 @@ def Tg_global(G, normalize: bool = True) -> dict[str, float]:
     total = sum(tg_total.values()) or 1.0
     out: dict[str, float] = {}
 
-    def add(g):
+    def add(g: str) -> None:
         val = float(tg_total.get(g, 0.0))
         out[g] = val / total if normalize else val
 
@@ -42,30 +44,32 @@ def Tg_global(G, normalize: bool = True) -> dict[str, float]:
     return out
 
 
-def Tg_by_node(G, n, normalize: bool = False) -> dict[str, float | list[float]]:
+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:
-        out: dict[str, list[float]] = {}
+        runs_out: dict[str, list[float]] = {}
 
-        def copy_runs(g):
-            out[g] = list(rec.get(g, []))
+        def copy_runs(g: str) -> None:
+            runs_out[g] = list(rec.get(g, []))
 
         for_each_glyph(copy_runs)
-        return out
-    out: dict[str, float] = {}
+        return runs_out
+    mean_out: dict[str, float] = {}
 
-    def add(g):
+    def add(g: str) -> None:
         runs = rec.get(g, [])
-        out[g] = float(mean(runs)) if runs else 0.0
+        mean_out[g] = float(mean(runs)) if runs else 0.0
 
     for_each_glyph(add)
-    return out
+    return mean_out
 
 
-def latency_series(G) -> dict[str, list[float]]:
+def latency_series(G: TNFRGraph) -> dict[str, list[float]]:
     hist = ensure_history(G)
     xs = hist.get("latency_index", [])
     return {
@@ -74,21 +78,21 @@ def latency_series(G) -> dict[str, list[float]]:
     }
 
 
-def glyphogram_series(G) -> dict[str, list[float]]:
+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):
+    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, k: int = 3) -> list[tuple[str, float]]:
+def glyph_top(G: TNFRGraph, k: int = 3) -> list[tuple[str, float]]:
     """Top-k structural operators by ``Tg_global`` fraction."""
 
     k = int(k)
@@ -99,8 +103,8 @@ def glyph_top(G, k: int = 3) -> list[tuple[str, float]]:
 
 
 def build_metrics_summary(
-    G, *, series_limit: int | None = None
-) -> tuple[dict[str, Any], bool]:
+    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
@@ -131,7 +135,7 @@ def build_metrics_summary(
         if limit <= 0:
             limit = None
 
-    def _trim(values: list[Any]) -> list[Any]:
+    def _trim(values: Sequence[Any]) -> list[Any]:
         seq = list(values)
         if limit is None:
             return seq

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