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

tnfr/sense.py

@@ -1,200 +1,365 @@
+"""Sense calculations."""
+
 from __future__ import annotations
-from typing import Dict, Any, List, Tuple
+from typing import Any, Callable, TypeVar
+from collections.abc import Iterable, Iterator, Mapping
 import math
 from collections import Counter
-
-from .constants import DEFAULTS, ALIAS_SI, ALIAS_EPI
-from .helpers import _get_attr, clamp01, register_callback, ensure_history, last_glifo
-
+from itertools import tee
+
+import networkx as nx
+
+from .constants import get_aliases, get_graph_param
+from .alias import get_attr
+from .helpers.numeric import clamp01, kahan_sum_nd
+from .utils import get_numpy
+from .callback_utils import CallbackEvent, callback_manager
+from .glyph_history import (
+    ensure_history,
+    last_glyph,
+    count_glyphs,
+    append_metric,
+)
+from .config.constants import (
+    ANGLE_MAP,
+    GLYPHS_CANONICAL,
+)
+from .types import NodeId, SigmaVector, TNFRGraph
 # -------------------------
-# Canon: orden circular de glifos y ángulos
+# Canon: circular glyph order and angles
 # -------------------------
-GLYPHS_CANONICAL: List[str] = [
-    "A’L",  # 0
-    "E’N",  # 1
-    "I’L",  # 2
-    "U’M",  # 3
-    "R’A",  # 4
-    "VA’L", # 5
-    "O’Z",  # 6
-    "Z’HIR",# 7
-    "NA’V", # 8
-    "T’HOL",# 9
-    "NU’L", #10
-    "SH’A", #11
-    "RE’MESH" #12
-]
-
-_SIGMA_ANGLES: Dict[str, float] = {g: (2.0*math.pi * i / len(GLYPHS_CANONICAL)) for i, g in enumerate(GLYPHS_CANONICAL)}
 
-# -------------------------
-# Config por defecto
-# -------------------------
-DEFAULTS.setdefault("SIGMA", {
-    "enabled": True,
-    "weight": "Si",      # "Si" | "EPI" | "1"
-    "smooth": 0.0,        # EMA sobre el vector global (0=off)
-    "history_key": "sigma_global",   # dónde guardar en G.graph['history']
-    "per_node": False,    # si True, guarda trayectoria σ por nodo (más pesado)
-})
+GLYPH_UNITS: dict[str, complex] = {
+    g: complex(math.cos(a), math.sin(a)) for g, a in ANGLE_MAP.items()
+}
+
+__all__ = (
+    "GLYPH_UNITS",
+    "glyph_angle",
+    "glyph_unit",
+    "sigma_vector_node",
+    "sigma_vector",
+    "sigma_vector_from_graph",
+    "push_sigma_snapshot",
+    "register_sigma_callback",
+    "sigma_rose",
+)
 
 # -------------------------
-# Utilidades básicas
+# Basic utilities
 # -------------------------
 
+
+T = TypeVar("T")
+
+
+def _resolve_glyph(g: str, mapping: Mapping[str, T]) -> T:
+    """Return ``mapping[g]`` or raise ``KeyError`` with a standard message."""
+
+    try:
+        return mapping[g]
+    except KeyError as e:  # pragma: no cover - small helper
+        raise KeyError(f"Unknown glyph: {g}") from e
+
+
 def glyph_angle(g: str) -> float:
-    return float(_SIGMA_ANGLES.get(g, 0.0))
+    """Return angle for glyph ``g``."""
+
+    return float(_resolve_glyph(g, ANGLE_MAP))
 
 
 def glyph_unit(g: str) -> complex:
-    a = glyph_angle(g)
-    return complex(math.cos(a), math.sin(a))
+    """Return unit vector for glyph ``g``."""
 
+    return _resolve_glyph(g, GLYPH_UNITS)
 
-def _weight(G, n, mode: str) -> float:
-    nd = G.nodes[n]
-    if mode == "Si":
-        return clamp01(_get_attr(nd, ALIAS_SI, 0.5))
-    if mode == "EPI":
-        return max(0.0, float(_get_attr(nd, ALIAS_EPI, 0.0)))
-    return 1.0
 
+ALIAS_SI = get_aliases("SI")
+ALIAS_EPI = get_aliases("EPI")
 
-    
-# -------------------------
-# σ por nodo y σ global
-# -------------------------
+MODE_FUNCS: dict[str, Callable[[Mapping[str, Any]], float]] = {
+    "Si": lambda nd: clamp01(get_attr(nd, ALIAS_SI, 0.5)),
+    "EPI": lambda nd: max(0.0, get_attr(nd, ALIAS_EPI, 0.0)),
+}
 
-def sigma_vector_node(G, n, weight_mode: str | None = None) -> Dict[str, float] | None:
-    nd = G.nodes[n]
-    g = last_glifo(nd)
-    if g is None:
+
+def _weight(nd: Mapping[str, Any], mode: str) -> float:
+    return MODE_FUNCS.get(mode, lambda _: 1.0)(nd)
+
+
+def _node_weight(
+    nd: Mapping[str, Any], weight_mode: str
+) -> tuple[str, float, complex] | None:
+    """Return ``(glyph, weight, weighted_unit)`` or ``None`` if no glyph."""
+    g = last_glyph(nd)
+    if not g:
         return None
-    w = _weight(G, n, weight_mode or G.graph.get("SIGMA", DEFAULTS["SIGMA"]).get("weight", "Si"))
-    z = glyph_unit(g) * w
-    x, y = z.real, z.imag
-    mag = math.hypot(x, y)
-    ang = math.atan2(y, x) if mag > 0 else glyph_angle(g)
-    return {"x": float(x), "y": float(y), "mag": float(mag), "angle": float(ang), "glifo": g, "w": float(w)}
+    w = _weight(nd, weight_mode)
+    z = glyph_unit(g) * w  # precompute weighted unit vector
+    return g, w, z
+
 
+def _sigma_cfg(G: TNFRGraph) -> dict[str, Any]:
+    return get_graph_param(G, "SIGMA", dict)
 
-def sigma_vector_global(G, weight_mode: str | None = None) -> Dict[str, float]:
-    """Vector global del plano del sentido σ.
 
-    Mapea el último glifo de cada nodo a un vector unitario en S¹, ponderado
-    por `Si` (o `EPI`/1), y promedia para obtener:
-      - componentes (x, y), magnitud |σ| y ángulo arg(σ).
+def _to_complex(val: complex | float | int) -> complex:
+    """Return ``val`` as complex, promoting real numbers."""
 
-    Interpretación TNFR: |σ| mide cuán alineada está la red en su
-    **recorrido glífico**; arg(σ) indica la **dirección funcional** dominante
-    (p. ej., torno a I’L/RA para consolidación/distribución, O’Z/Z’HIR para cambio).
+    if isinstance(val, complex):
+        return val
+    if isinstance(val, (int, float)):
+        return complex(val, 0.0)
+    raise TypeError("values must be an iterable of real or complex numbers")
+
+
+def _empty_sigma(fallback_angle: float) -> SigmaVector:
+    """Return an empty σ-vector with ``fallback_angle``.
+
+    Helps centralise the default structure returned when no values are
+    available for σ calculations.
     """
-    cfg = G.graph.get("SIGMA", DEFAULTS["SIGMA"])
-    weight_mode = weight_mode or cfg.get("weight", "Si")
-    acc = complex(0.0, 0.0)
+
+    return {
+        "x": 0.0,
+        "y": 0.0,
+        "mag": 0.0,
+        "angle": float(fallback_angle),
+        "n": 0,
+    }
+
+
+# -------------------------
+# σ per node and global σ
+# -------------------------
+
+
+def _sigma_from_iterable(
+    values: Iterable[complex | float | int] | complex | float | int,
+    fallback_angle: float = 0.0,
+) -> SigmaVector:
+    """Normalise vectors in the σ-plane.
+
+    ``values`` may contain complex or real numbers; real inputs are promoted to
+    complex with zero imaginary part. The returned dictionary includes the
+    number of processed values under the ``"n"`` key.
+    """
+
+    if isinstance(values, Iterable) and not isinstance(values, (str, bytes, bytearray, Mapping)):
+        iterator = iter(values)
+    else:
+        iterator = iter((values,))
+
+    np = get_numpy()
+    if np is not None:
+        iterator, np_iter = tee(iterator)
+        arr = np.fromiter((_to_complex(v) for v in np_iter), dtype=np.complex128)
+        cnt = int(arr.size)
+        if cnt == 0:
+            return _empty_sigma(fallback_angle)
+        x = float(np.mean(arr.real))
+        y = float(np.mean(arr.imag))
+        mag = float(np.hypot(x, y))
+        ang = float(np.arctan2(y, x)) if mag > 0 else float(fallback_angle)
+        return {
+            "x": float(x),
+            "y": float(y),
+            "mag": float(mag),
+            "angle": float(ang),
+            "n": int(cnt),
+        }
     cnt = 0
-    for n in G.nodes():
-        v = sigma_vector_node(G, n, weight_mode)
-        if v is None:
-            continue
-        acc += complex(v["x"], v["y"])
-        cnt += 1
+
+    def pair_iter() -> Iterator[tuple[float, float]]:
+        nonlocal cnt
+        for val in iterator:
+            z = _to_complex(val)
+            cnt += 1
+            yield (z.real, z.imag)
+
+    sum_x, sum_y = kahan_sum_nd(pair_iter(), dims=2)
+
     if cnt == 0:
-        return {"x": 1.0, "y": 0.0, "mag": 1.0, "angle": 0.0, "n": 0}
-    x, y = acc.real / max(1, cnt), acc.imag / max(1, cnt)
+        return _empty_sigma(fallback_angle)
+
+    x = sum_x / cnt
+    y = sum_y / cnt
+    mag = math.hypot(x, y)
+    ang = math.atan2(y, x) if mag > 0 else float(fallback_angle)
+    return {
+        "x": float(x),
+        "y": float(y),
+        "mag": float(mag),
+        "angle": float(ang),
+        "n": int(cnt),
+    }
+
+
+def _ema_update(
+    prev: SigmaVector, current: SigmaVector, alpha: float
+) -> SigmaVector:
+    """Exponential moving average update for σ vectors."""
+    x = (1 - alpha) * prev["x"] + alpha * current["x"]
+    y = (1 - alpha) * prev["y"] + alpha * current["y"]
     mag = math.hypot(x, y)
     ang = math.atan2(y, x)
-    return {"x": float(x), "y": float(y), "mag": float(mag), "angle": float(ang), "n": cnt}
+    return {
+        "x": float(x),
+        "y": float(y),
+        "mag": float(mag),
+        "angle": float(ang),
+        "n": int(current["n"]),
+    }
+
+
+def _sigma_from_nodes(
+    nodes: Iterable[Mapping[str, Any]],
+    weight_mode: str,
+    fallback_angle: float = 0.0,
+) -> tuple[SigmaVector, list[tuple[str, float, complex]]]:
+    """Aggregate weighted glyph vectors for ``nodes``.
+
+    Returns the aggregated σ vector and the list of ``(glyph, weight, vector)``
+    triples used in the calculation.
+    """
+
+    nws = [nw for nd in nodes if (nw := _node_weight(nd, weight_mode))]
+    sv = _sigma_from_iterable((nw[2] for nw in nws), fallback_angle)
+    return sv, nws
+
+
+def sigma_vector_node(
+    G: TNFRGraph, n: NodeId, weight_mode: str | None = None
+) -> SigmaVector | None:
+    cfg = _sigma_cfg(G)
+    nd = G.nodes[n]
+    weight_mode = weight_mode or cfg.get("weight", "Si")
+    sv, nws = _sigma_from_nodes([nd], weight_mode)
+    if not nws:
+        return None
+    g, w, _ = nws[0]
+    if sv["mag"] == 0:
+        sv["angle"] = glyph_angle(g)
+    sv["glyph"] = g
+    sv["w"] = float(w)
+    return sv
+
+
+def sigma_vector(dist: Mapping[str, float]) -> SigmaVector:
+    """Compute Σ⃗ from a glyph distribution.
+
+    ``dist`` may contain raw counts or proportions. All ``(glyph, weight)``
+    pairs are converted to vectors and passed to :func:`_sigma_from_iterable`.
+    The resulting vector includes the number of processed pairs under ``n``.
+    """
+
+    vectors = (glyph_unit(g) * float(w) for g, w in dist.items())
+    return _sigma_from_iterable(vectors)
+
+
+def sigma_vector_from_graph(
+    G: TNFRGraph, weight_mode: str | None = None
+) -> SigmaVector:
+    """Global vector in the σ sense plane for a graph.
+
+    Parameters
+    ----------
+    G:
+        NetworkX graph with per-node states.
+    weight_mode:
+        How to weight each node ("Si", "EPI" or ``None`` for unit weight).
+
+    Returns
+    -------
+    dict[str, float]
+        Cartesian components, magnitude and angle of the average vector.
+    """
+
+    if not isinstance(G, nx.Graph):
+        raise TypeError("sigma_vector_from_graph requires a networkx.Graph")
+
+    cfg = _sigma_cfg(G)
+    weight_mode = weight_mode or cfg.get("weight", "Si")
+    sv, _ = _sigma_from_nodes(
+        (nd for _, nd in G.nodes(data=True)), weight_mode
+    )
+    return sv
 
 
 # -------------------------
-# Historia / series
+# History / series
 # -------------------------
 
-def push_sigma_snapshot(G, t: float | None = None) -> None:
-    cfg = G.graph.get("SIGMA", DEFAULTS["SIGMA"])
+
+def push_sigma_snapshot(G: TNFRGraph, t: float | None = None) -> None:
+    cfg = _sigma_cfg(G)
     if not cfg.get("enabled", True):
         return
+
+    # Local history cache to avoid repeated lookups
     hist = ensure_history(G)
     key = cfg.get("history_key", "sigma_global")
 
-    # Global
-    sv = sigma_vector_global(G, cfg.get("weight", "Si"))
+    weight_mode = cfg.get("weight", "Si")
+    sv = sigma_vector_from_graph(G, weight_mode)
 
-    # Suavizado exponencial (EMA) opcional
+    # Optional exponential smoothing (EMA)
     alpha = float(cfg.get("smooth", 0.0))
     if alpha > 0 and hist.get(key):
-        prev = hist[key][-1]
-        x = (1-alpha)*prev["x"] + alpha*sv["x"]
-        y = (1-alpha)*prev["y"] + alpha*sv["y"]
-        mag = math.hypot(x, y)
-        ang = math.atan2(y, x)
-        sv = {"x": x, "y": y, "mag": mag, "angle": ang, "n": sv.get("n", 0)}
-
-    sv["t"] = float(G.graph.get("_t", 0.0) if t is None else t)
-
-    hist.setdefault(key, []).append(sv)
-
-    # Conteo de glifos por paso (útil para rosa glífica)
-    counts = Counter()
-    for n in G.nodes():
-        g = last_glifo(G.nodes[n])
-        if g:
-            counts[g] += 1
-    hist.setdefault("sigma_counts", []).append({"t": sv["t"], **counts})
-
-    # Trayectoria por nodo (opcional)
+        sv = _ema_update(hist[key][-1], sv, alpha)
+
+    current_t = float(G.graph.get("_t", 0.0) if t is None else t)
+    sv["t"] = current_t
+
+    append_metric(hist, key, sv)
+
+    # Glyph count per step (useful for the glyph rose)
+    counts = count_glyphs(G, last_only=True)
+    append_metric(hist, "sigma_counts", {"t": current_t, **counts})
+
+    # Optional per-node trajectory
     if cfg.get("per_node", False):
         per = hist.setdefault("sigma_per_node", {})
-        for n in G.nodes():
-            nd = G.nodes[n]
-            g = last_glifo(nd)
+        for n, nd in G.nodes(data=True):
+            g = last_glyph(nd)
             if not g:
                 continue
-            a = glyph_angle(g)
             d = per.setdefault(n, [])
-            d.append({"t": sv["t"], "g": g, "angle": a})
+            d.append({"t": current_t, "g": g, "angle": glyph_angle(g)})
 
 
 # -------------------------
-# Registro como callback automático (after_step)
+# Register as an automatic callback (after_step)
 # -------------------------
 
-def register_sigma_callback(G) -> None:
-    register_callback(G, when="after_step", func=push_sigma_snapshot, name="sigma_snapshot")
-
-
-# -------------------------
-# Series de utilidad
-# -------------------------
 
-def sigma_series(G, key: str | None = None) -> Dict[str, List[float]]:
-    cfg = G.graph.get("SIGMA", DEFAULTS["SIGMA"])
-    key = key or cfg.get("history_key", "sigma_global")
-    hist = G.graph.get("history", {})
-    xs = hist.get(key, [])
-    if not xs:
-        return {"t": [], "angle": [], "mag": []}
-    return {
-        "t": [float(x.get("t", i)) for i, x in enumerate(xs)],
-        "angle": [float(x["angle"]) for x in xs],
-        "mag": [float(x["mag"]) for x in xs],
-    }
+def register_sigma_callback(G: TNFRGraph) -> None:
+    callback_manager.register_callback(
+        G,
+        event=CallbackEvent.AFTER_STEP.value,
+        func=push_sigma_snapshot,
+        name="sigma_snapshot",
+    )
 
 
-def sigma_rose(G, steps: int | None = None) -> Dict[str, int]:
-    """Histograma de glifos en los últimos `steps` pasos (o todos)."""
-    hist = G.graph.get("history", {})
+def sigma_rose(G: TNFRGraph, steps: int | None = None) -> dict[str, int]:
+    """Histogram of glyphs in the last ``steps`` steps (or all)."""
+    hist = ensure_history(G)
     counts = hist.get("sigma_counts", [])
     if not counts:
         return {g: 0 for g in GLYPHS_CANONICAL}
-    if steps is None or steps >= len(counts):
-        agg = Counter()
-        for row in counts:
-            agg.update({k: v for k, v in row.items() if k != "t"})
-        out = {g: int(agg.get(g, 0)) for g in GLYPHS_CANONICAL}
-        return out
-    agg = Counter()
-    for row in counts[-int(steps):]:
-        agg.update({k: v for k, v in row.items() if k != "t"})
-    return {g: int(agg.get(g, 0)) for g in GLYPHS_CANONICAL}
+    if steps is not None:
+        steps = int(steps)
+        if steps < 0:
+            raise ValueError("steps must be non-negative")
+        rows = (
+            counts if steps >= len(counts) else counts[-steps:]
+        )  # noqa: E203
+    else:
+        rows = counts
+    counter = Counter()
+    for row in rows:
+        for k, v in row.items():
+            if k != "t":
+                counter[k] += int(v)
+    return {g: int(counter.get(g, 0)) for g in GLYPHS_CANONICAL}

tnfr/sense.pyi

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Optional
+
+from .types import NodeId, SigmaVector, TNFRGraph
+
+__all__: tuple[str, ...]
+
+GLYPH_UNITS: dict[str, complex]
+
+def glyph_angle(g: str) -> float: ...
+
+def glyph_unit(g: str) -> complex: ...
+
+def push_sigma_snapshot(G: TNFRGraph, t: Optional[float] = None) -> None: ...
+
+def register_sigma_callback(G: TNFRGraph) -> None: ...
+
+def sigma_rose(G: TNFRGraph, steps: Optional[int] = None) -> dict[str, int]: ...
+
+def sigma_vector(dist: Mapping[str, float]) -> SigmaVector: ...
+
+def sigma_vector_from_graph(
+    G: TNFRGraph, weight_mode: Optional[str] = None
+) -> SigmaVector: ...
+
+def sigma_vector_node(
+    G: TNFRGraph, n: NodeId, weight_mode: Optional[str] = None
+) -> Optional[SigmaVector]: ...