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

tnfr/node.pyi

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterable, MutableMapping
+from typing import Any, Callable, Optional, Protocol, SupportsFloat, TypeVar
+
+from .types import (
+    CouplingWeight,
+    DeltaNFR,
+    EPIValue,
+    NodeId,
+    Phase,
+    SecondDerivativeEPI,
+    SenseIndex,
+    StructuralFrequency,
+    TNFRGraph,
+)
+
+T = TypeVar("T")
+
+__all__ = ("NodeNX", "NodeProtocol", "add_edge")
+
+
+class AttrSpec:
+    aliases: tuple[str, ...]
+    default: Any
+    getter: Callable[[MutableMapping[str, Any], tuple[str, ...], Any], Any]
+    setter: Callable[..., None]
+    to_python: Callable[[Any], Any]
+    to_storage: Callable[[Any], Any]
+    use_graph_setter: bool
+
+    def build_property(self) -> property: ...
+
+
+ALIAS_EPI: tuple[str, ...]
+ALIAS_VF: tuple[str, ...]
+ALIAS_THETA: tuple[str, ...]
+ALIAS_SI: tuple[str, ...]
+ALIAS_EPI_KIND: tuple[str, ...]
+ALIAS_DNFR: tuple[str, ...]
+ALIAS_D2EPI: tuple[str, ...]
+
+ATTR_SPECS: dict[str, AttrSpec]
+
+
+def _add_edge_common(
+    n1: NodeId,
+    n2: NodeId,
+    weight: CouplingWeight | SupportsFloat | str,
+) -> Optional[CouplingWeight]: ...
+
+
+def add_edge(
+    graph: TNFRGraph,
+    n1: NodeId,
+    n2: NodeId,
+    weight: CouplingWeight | SupportsFloat | str,
+    overwrite: bool = ...,
+) -> None: ...
+
+
+class NodeProtocol(Protocol):
+    EPI: EPIValue
+    vf: StructuralFrequency
+    theta: Phase
+    Si: SenseIndex
+    epi_kind: str
+    dnfr: DeltaNFR
+    d2EPI: SecondDerivativeEPI
+    graph: MutableMapping[str, Any]
+
+    def neighbors(self) -> Iterable[NodeProtocol | Hashable]: ...
+
+    def _glyph_storage(self) -> MutableMapping[str, object]: ...
+
+    def has_edge(self, other: NodeProtocol) -> bool: ...
+
+    def add_edge(
+        self,
+        other: NodeProtocol,
+        weight: CouplingWeight,
+        *,
+        overwrite: bool = ...,
+    ) -> None: ...
+
+    def offset(self) -> int: ...
+
+    def all_nodes(self) -> Iterable[NodeProtocol]: ...
+
+
+class NodeNX(NodeProtocol):
+    G: TNFRGraph
+    n: NodeId
+    graph: MutableMapping[str, Any]
+
+    def __init__(self, G: TNFRGraph, n: NodeId) -> None: ...
+
+    @classmethod
+    def from_graph(cls, G: TNFRGraph, n: NodeId) -> "NodeNX": ...
+
+    def _glyph_storage(self) -> MutableMapping[str, Any]: ...
+
+    @property
+    def EPI(self) -> EPIValue: ...
+
+    @EPI.setter
+    def EPI(self, value: EPIValue) -> None: ...
+
+    @property
+    def vf(self) -> StructuralFrequency: ...
+
+    @vf.setter
+    def vf(self, value: StructuralFrequency) -> None: ...
+
+    @property
+    def theta(self) -> Phase: ...
+
+    @theta.setter
+    def theta(self, value: Phase) -> None: ...
+
+    @property
+    def Si(self) -> SenseIndex: ...
+
+    @Si.setter
+    def Si(self, value: SenseIndex) -> None: ...
+
+    @property
+    def epi_kind(self) -> str: ...
+
+    @epi_kind.setter
+    def epi_kind(self, value: str) -> None: ...
+
+    @property
+    def dnfr(self) -> DeltaNFR: ...
+
+    @dnfr.setter
+    def dnfr(self, value: DeltaNFR) -> None: ...
+
+    @property
+    def d2EPI(self) -> SecondDerivativeEPI: ...
+
+    @d2EPI.setter
+    def d2EPI(self, value: SecondDerivativeEPI) -> None: ...
+
+    def neighbors(self) -> Iterable[NodeId]: ...
+
+    def has_edge(self, other: NodeProtocol) -> bool: ...
+
+    def add_edge(
+        self,
+        other: NodeProtocol,
+        weight: CouplingWeight,
+        *,
+        overwrite: bool = ...,
+    ) -> None: ...
+
+    def offset(self) -> int: ...
+
+    def all_nodes(self) -> Iterable[NodeProtocol]: ...
+
+

tnfr/observers.py

@@ -1,169 +1,173 @@
-"""
-observers.py — TNFR canónica
+"""Observer management."""
 
-Observadores y métricas auxiliares.
-"""
 from __future__ import annotations
-from collections import Counter
-from typing import Dict, Any
-import math
 
-from .constants import ALIAS_DNFR, ALIAS_EPI, ALIAS_THETA, ALIAS_dEPI
-from .helpers import _get_attr, list_mean, register_callback
+from collections.abc import Mapping
+from functools import partial
+import statistics
+from statistics import StatisticsError, pvariance
+
+from .alias import get_theta_attr
+from .helpers.numeric import angle_diff
+from .callback_utils import CallbackEvent, callback_manager
+from .glyph_history import (
+    ensure_history,
+    count_glyphs,
+    append_metric,
+)
+from .types import Glyph, GlyphLoadDistribution, TNFRGraph
+from .utils import (
+    get_logger,
+    get_numpy,
+    mix_groups,
+    normalize_counter,
+    validate_window,
+)
+from .config.constants import GLYPH_GROUPS
+from .gamma import kuramoto_R_psi
+from .metrics.common import compute_coherence
+
+__all__ = (
+    "attach_standard_observer",
+    "kuramoto_metrics",
+    "phase_sync",
+    "kuramoto_order",
+    "glyph_load",
+    "wbar",
+    "DEFAULT_GLYPH_LOAD_SPAN",
+    "DEFAULT_WBAR_SPAN",
+)
+
+
+logger = get_logger(__name__)
+
+DEFAULT_GLYPH_LOAD_SPAN = 50
+DEFAULT_WBAR_SPAN = 25
+
 
 # -------------------------
-# Observador estándar Γ(R)
+# Standard Γ(R) observer
 # -------------------------
-def _std_log(G, kind: str, ctx: dict):
-    """Guarda eventos compactos en history['events']."""
-    h = G.graph.setdefault("history", {})
-    h.setdefault("events", []).append((kind, dict(ctx)))
-
-def std_before(G, ctx):
-    _std_log(G, "before", ctx)
-
-def std_after(G, ctx):
-    _std_log(G, "after", ctx)
-
-def std_on_remesh(G, ctx):
-    _std_log(G, "remesh", ctx)
-
-def attach_standard_observer(G):
-    """Registra callbacks estándar: before_step, after_step, on_remesh."""
-    register_callback(G, "before_step", std_before)
-    register_callback(G, "after_step",  std_after)
-    register_callback(G, "on_remesh",   std_on_remesh)
-    G.graph.setdefault("_STD_OBSERVER", "attached")
+def _std_log(kind: str, G: TNFRGraph, ctx: Mapping[str, object]) -> None:
+    """Store compact events in ``history['events']``."""
+    h = ensure_history(G)
+    append_metric(h, "events", (kind, dict(ctx)))
+
+
+_STD_CALLBACKS = {
+    CallbackEvent.BEFORE_STEP.value: partial(_std_log, "before"),
+    CallbackEvent.AFTER_STEP.value: partial(_std_log, "after"),
+    CallbackEvent.ON_REMESH.value: partial(_std_log, "remesh"),
+}
+
+
+def attach_standard_observer(G: TNFRGraph) -> TNFRGraph:
+    """Register standard callbacks: before_step, after_step, on_remesh."""
+    if G.graph.get("_STD_OBSERVER"):
+        return G
+    for event, fn in _STD_CALLBACKS.items():
+        callback_manager.register_callback(G, event, fn)
+    G.graph["_STD_OBSERVER"] = "attached"
     return G
 
-def coherencia_global(G) -> float:
-    """Proxy de C(t): alta cuando |ΔNFR| y |dEPI_dt| son pequeños."""
-    dnfr = list_mean(abs(_get_attr(G.nodes[n], ALIAS_DNFR, 0.0)) for n in G.nodes())
-    dEPI = list_mean(abs(_get_attr(G.nodes[n], ALIAS_dEPI, 0.0)) for n in G.nodes())
-    return 1.0 / (1.0 + dnfr + dEPI)
+
+def _ensure_nodes(G: TNFRGraph) -> bool:
+    """Return ``True`` when the graph has nodes."""
+    return bool(G.number_of_nodes())
+
+
+def kuramoto_metrics(G: TNFRGraph) -> tuple[float, float]:
+    """Return Kuramoto order ``R`` and mean phase ``ψ``.
+
+    Delegates to :func:`kuramoto_R_psi` and performs the computation exactly
+    once per invocation.
+    """
+    return kuramoto_R_psi(G)
 
 
-def sincronía_fase(G) -> float:
-    X = [math.cos(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
-    Y = [math.sin(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
-    if not X:
+def phase_sync(
+    G: TNFRGraph,
+    R: float | None = None,
+    psi: float | None = None,
+) -> float:
+    if not _ensure_nodes(G):
         return 1.0
-    th = math.atan2(sum(Y) / len(Y), sum(X) / len(X))
-    # varianza angular aproximada (0 = muy sincronizado)
-    import statistics as st
-    var = (
-        st.pvariance(
-            [
-                (
-                    (_get_attr(G.nodes[n], ALIAS_THETA, 0.0) - th + math.pi)
-                    % (2 * math.pi)
-                    - math.pi
-                )
-                for n in G.nodes()
-            ]
-        )
-        if len(X) > 1
-        else 0.0
-    )
+    if R is None or psi is None:
+        R_calc, psi_calc = kuramoto_metrics(G)
+        if R is None:
+            R = R_calc
+        if psi is None:
+            psi = psi_calc
+    def _theta(nd: Mapping[str, object]) -> float:
+        value = get_theta_attr(nd, 0.0)
+        return float(value) if value is not None else 0.0
+
+    diffs = (angle_diff(_theta(data), psi) for _, data in G.nodes(data=True))
+    # Try NumPy for a vectorised population variance
+    np = get_numpy()
+    if np is not None:
+        arr = np.fromiter(diffs, dtype=float)
+        var = float(np.var(arr)) if arr.size else 0.0
+    else:
+        try:
+            var = pvariance(diffs)
+        except StatisticsError:
+            var = 0.0
     return 1.0 / (1.0 + var)
 
-def orden_kuramoto(G) -> float:
-    """R en [0,1], 1 = fases perfectamente alineadas."""
-    X = [math.cos(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
-    Y = [math.sin(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
-    if not X:
+
+def kuramoto_order(
+    G: TNFRGraph, R: float | None = None, psi: float | None = None
+) -> float:
+    """R in [0,1], 1 means perfectly aligned phases."""
+    if not _ensure_nodes(G):
         return 1.0
-    R = ((sum(X)**2 + sum(Y)**2) ** 0.5) / max(1, len(X))
+    if R is None or psi is None:
+        R, psi = kuramoto_metrics(G)
     return float(R)
 
-def carga_glifica(G, window: int | None = None) -> dict:
-    """Devuelve distribución de glifos aplicados en la red.
-    - window: si se indica, cuenta solo los últimos `window` eventos por nodo; si no, usa el maxlen del deque.
-    Retorna un dict con proporciones por glifo y agregados útiles.
+
+def glyph_load(G: TNFRGraph, window: int | None = None) -> GlyphLoadDistribution:
+    """Return distribution of glyphs applied in the network.
+
+    - ``window``: if provided, count only the last ``window`` events per node;
+      otherwise use :data:`DEFAULT_GLYPH_LOAD_SPAN`.
+    Returns a dict with proportions per glyph and useful aggregates.
     """
-    total = Counter()
-    for n in G.nodes():
-        nd = G.nodes[n]
-        hist = nd.get("hist_glifos")
-        if not hist:
-            continue
-        seq = list(hist)
-        if window is not None and window > 0:
-            seq = seq[-window:]
-        total.update(seq)
-
-
-    count = sum(total.values())
+    if window == 0:
+        return {"_count": 0.0}
+    if window is None:
+        window_int = DEFAULT_GLYPH_LOAD_SPAN
+    else:
+        window_int = validate_window(window, positive=True)
+    total = count_glyphs(G, window=window_int, last_only=(window_int == 1))
+    dist_raw, count = normalize_counter(total)
     if count == 0:
-        return {"_count": 0}
-
-
-    # Proporciones por glifo
-    dist = {k: v / count for k, v in total.items()}
-
-    # Agregados conceptuales (puedes ajustar categorías)
-    # Glifos que consolidan la coherencia nodal: I’L estabiliza el flujo (cap. 6),
-    # R’A propaga la resonancia (cap. 9), U’M acopla nodos en fase (cap. 8)
-    # y SH’A ofrece silencio regenerativo (cap. 10). Véase manual TNFR,
-    # sec. 18.19 "Análisis morfosintáctico" para la taxonomía funcional.
-    estabilizadores = ["I’L", "R’A", "U’M", "SH’A"]
-
-    # Glifos que perturban o reconfiguran la red: O’Z introduce disonancia
-    # evolutiva (cap. 7), Z’HIR muta la estructura (cap. 14), NA’V marca
-    # el tránsito entre estados (cap. 15) y T’HOL autoorganiza un nuevo
-    # orden (cap. 13). Véase manual TNFR, sec. 18.19 para esta clasificación.
-    disruptivos = ["O’Z", "Z’HIR", "NA’V", "T’HOL"]
-
-
-    dist["_estabilizadores"] = sum(dist.get(k, 0.0) for k in estabilizadores)
-    dist["_disruptivos"] = sum(dist.get(k, 0.0) for k in disruptivos)
-    dist["_count"] = count
-    return dist
-
-def sigma_vector(G, window: int | None = None) -> dict:
-    """Vector de sentido Σ⃗ a partir de la distribución glífica reciente.
-    Devuelve dict con x, y, mag (0..1) y angle (rad)."""
-    # Distribución glífica (proporciones)
-    dist = carga_glifica(G, window=window)
-    if not dist or dist.get("_count", 0) == 0:
-        return {"x": 0.0, "y": 0.0, "mag": 0.0, "angle": 0.0}
-
-    # Mapeo polar de glifos principales en el plano de sentido
-    # (ordenado estabilización→expansión→acoplamiento→silencio→disonancia→mutación→transición→autoorg.)
-    angles = {
-        "I’L": 0.0,
-        "R’A": math.pi/4,
-        "U’M": math.pi/2,
-        "SH’A": 3*math.pi/4,
-        "O’Z": math.pi,
-        "Z’HIR": 5*math.pi/4,
-        "NA’V": 3*math.pi/2,
-        "T’HOL": 7*math.pi/4,
-    }
-    # Normaliza solo sobre glifos mapeados
-    total = sum(dist.get(k, 0.0) for k in angles.keys())
-    if total <= 0:
-        return {"x": 0.0, "y": 0.0, "mag": 0.0, "angle": 0.0}
-
-    x = 0.0
-    y = 0.0
-    for k, a in angles.items():
-        p = dist.get(k, 0.0) / total
-        x += p * math.cos(a)
-        y += p * math.sin(a)
-
-    mag = (x*x + y*y) ** 0.5
-    ang = math.atan2(y, x)
-    return {"x": float(x), "y": float(y), "mag": float(mag), "angle": float(ang)}
-
-def wbar(G, window: int | None = None) -> float:
-    """Devuelve W̄ = media de C(t) en una ventana reciente."""
-    hist = G.graph.get("history", {})
-    cs = hist.get("C_steps", [])
+        return {"_count": 0.0}
+    dist = mix_groups(dist_raw, GLYPH_GROUPS)
+    glyph_dist: GlyphLoadDistribution = {}
+    for key, value in dist.items():
+        try:
+            glyph_key: Glyph | str = Glyph(key)
+        except ValueError:
+            glyph_key = key
+        glyph_dist[glyph_key] = value
+    glyph_dist["_count"] = float(count)
+    return glyph_dist
+
+
+def wbar(G: TNFRGraph, window: int | None = None) -> float:
+    """Return W̄ = mean of ``C(t)`` over a recent window.
+
+    Uses :func:`ensure_history` to obtain ``G.graph['history']`` and falls back
+    to the instantaneous coherence when ``"C_steps"`` is missing or empty.
+    """
+    hist = ensure_history(G)
+    cs = list(hist.get("C_steps", []))
     if not cs:
-        # fallback: coherencia instantánea
-        return coherencia_global(G)
-    if window is None:
-        window = int(G.graph.get("WBAR_WINDOW", 25))
-    w = min(len(cs), max(1, int(window)))
-    return float(sum(cs[-w:]) / w)
+        # fallback: instantaneous coherence
+        return compute_coherence(G)
+    w_param = DEFAULT_WBAR_SPAN if window is None else window
+    w = validate_window(w_param, positive=True)
+    w = min(len(cs), w)
+    return float(statistics.fmean(cs[-w:]))

tnfr/observers.pyi

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Final
+
+from .types import GlyphLoadDistribution, TNFRGraph
+
+__all__: tuple[str, ...]
+
+DEFAULT_GLYPH_LOAD_SPAN: Final[int]
+DEFAULT_WBAR_SPAN: Final[int]
+
+
+def _std_log(kind: str, G: TNFRGraph, ctx: Mapping[str, object]) -> None: ...
+
+
+def attach_standard_observer(G: TNFRGraph) -> TNFRGraph: ...
+
+
+def _ensure_nodes(G: TNFRGraph) -> bool: ...
+
+
+def kuramoto_metrics(G: TNFRGraph) -> tuple[float, float]: ...
+
+
+def phase_sync(
+    G: TNFRGraph,
+    R: float | None = ...,
+    psi: float | None = ...,
+) -> float: ...
+
+
+def kuramoto_order(
+    G: TNFRGraph,
+    R: float | None = ...,
+    psi: float | None = ...,
+) -> float: ...
+
+
+def glyph_load(
+    G: TNFRGraph,
+    window: int | None = ...,
+) -> GlyphLoadDistribution: ...
+
+
+def wbar(G: TNFRGraph, window: int | None = ...) -> float: ...