tnfr 3.0.3__py3-none-any.whl → 4.0.0__py3-none-any.whl

tnfr/__init__.py

@@ -1,56 +1,57 @@
-from __future__ import annotations
-"""
-TNFR — Teoría de la Naturaleza Fractal Resonante
-API pública del paquete.
-
-Ecuación nodal:
-    ∂EPI/∂t = νf · ΔNFR(t)
-"""
-
-__version__ = "3.0.3"
-
-import sys as _sys
-
-# ------------------------------------------------------------
-# 1) Crear alias para módulos con imports absolutos entre sí
-#    (los submódulos usan cosas tipo `from constants import ...`)
-#    Por eso registramos primero: constants → helpers → operators → observers
-# ------------------------------------------------------------
-from . import constants as _constants
-_sys.modules.setdefault("constants", _constants)
-
-from . import helpers as _helpers
-_sys.modules.setdefault("helpers", _helpers)
-
-from . import operators as _operators
-_sys.modules.setdefault("operators", _operators)
-
-from . import observers as _observers
-_sys.modules.setdefault("observers", _observers)
-
-# ------------------------------------------------------------
-# 2) IMPORTAR dynamics y ALIAS antes de ontosim
-#    (porque ontosim hace `from dynamics import ...`)
-# ------------------------------------------------------------
-from . import dynamics as _dynamics
-_sys.modules.setdefault("dynamics", _dynamics)
-
-# ------------------------------------------------------------
-# 3) Ahora sí, importar ontosim y alias
-# ------------------------------------------------------------
-from . import ontosim as _ontosim
-_sys.modules.setdefault("ontosim", _ontosim)
-
-# ------------------------------------------------------------
-# 4) Re-exports de la API pública
-# ------------------------------------------------------------
-from .dynamics import step, run, set_delta_nfr_hook
-from .ontosim import preparar_red
-from .observers import attach_standard_observer, coherencia_global, orden_kuramoto
-
-__all__ = [
-    "preparar_red",
-    "step", "run", "set_delta_nfr_hook",
-    "attach_standard_observer", "coherencia_global", "orden_kuramoto",
-    "__version__",
-]
+
+from __future__ import annotations
+"""
+TNFR — Teoría de la Naturaleza Fractal Resonante
+API pública del paquete.
+
+Ecuación nodal:
+    ∂EPI/∂t = νf · ΔNFR(t)
+"""
+
+__version__ = "4.0.0"
+
+# Re-exports de la API pública
+from .dynamics import step, run, set_delta_nfr_hook
+from .ontosim import preparar_red
+from .observers import attach_standard_observer, coherencia_global, orden_kuramoto
+from .gamma import GAMMA_REGISTRY, eval_gamma, kuramoto_R_psi
+from .grammar import enforce_canonical_grammar, on_applied_glifo
+from .sense import (
+    GLYPHS_CANONICAL, glyph_angle, glyph_unit,
+    sigma_vector_node, sigma_vector_global,
+    push_sigma_snapshot, sigma_series, sigma_rose,
+    register_sigma_callback,
+)
+from .metrics import (
+    register_metrics_callbacks,
+    Tg_global, Tg_by_node,
+    latency_series, glifogram_series,
+    glyph_top, glyph_dwell_stats,
+)
+from .trace import register_trace
+from .program import play, seq, block, target, wait, THOL, TARGET, WAIT
+from .cli import main as cli_main
+from .scenarios import build_graph
+from .presets import get_preset
+from .types import NodeState
+
+__all__ = [
+    "preparar_red",
+    "step", "run", "set_delta_nfr_hook",
+    "attach_standard_observer", "coherencia_global", "orden_kuramoto",
+    "GAMMA_REGISTRY", "eval_gamma", "kuramoto_R_psi",
+    "enforce_canonical_grammar", "on_applied_glifo",
+    "GLYPHS_CANONICAL", "glyph_angle", "glyph_unit",
+    "sigma_vector_node", "sigma_vector_global",
+    "push_sigma_snapshot", "sigma_series", "sigma_rose",
+    "register_sigma_callback",
+    "register_metrics_callbacks",
+    "register_trace",
+    "Tg_global", "Tg_by_node",
+    "latency_series", "glifogram_series",
+    "glyph_top", "glyph_dwell_stats",
+    "play", "seq", "block", "target", "wait", "THOL", "TARGET", "WAIT",
+    "__version__",
+]
+
+__all__ += ["cli_main", "build_graph", "get_preset", "NodeState"]

tnfr/cli.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+import argparse
+import json
+from typing import Any, Dict, List, Optional
+
+try:  # pragma: no cover - opcional
+    import yaml  # type: ignore
+except Exception:  # pragma: no cover - yaml es opcional
+    yaml = None
+
+import networkx as nx
+
+from .constants import inject_defaults, DEFAULTS
+from .sense import register_sigma_callback, sigma_series, sigma_rose
+from .metrics import (
+    register_metrics_callbacks,
+    Tg_global,
+    latency_series,
+    glifogram_series,
+    glyph_top,
+)
+from .trace import register_trace
+from .program import play, seq, block, wait, target
+from .dynamics import step, _update_history
+from .scenarios import build_graph
+from .presets import get_preset
+
+
+def _save_json(path: str, data: Any) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+
+
+def _load_sequence(path: str) -> List[Any]:
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+    if path.endswith(".yaml") or path.endswith(".yml"):
+        if not yaml:
+            raise RuntimeError("pyyaml no está instalado, usa JSON o instala pyyaml")
+        data = yaml.safe_load(text)
+    else:
+        data = json.loads(text)
+
+    def parse_token(tok: Any):
+        if isinstance(tok, str):
+            return tok
+        if isinstance(tok, dict):
+            if "WAIT" in tok:
+                return wait(int(tok["WAIT"]))
+            if "TARGET" in tok:
+                return target(tok["TARGET"])
+            if "THOL" in tok:
+                spec = tok["THOL"] or {}
+                b = [_parse_inner(x) for x in spec.get("body", [])]
+                return block(*b, repeat=int(spec.get("repeat", 1)), close=spec.get("close"))
+        raise ValueError(f"Token inválido: {tok}")
+
+    def _parse_inner(x: Any):
+        return parse_token(x)
+
+    return [parse_token(t) for t in data]
+
+
+def _attach_callbacks(G: nx.Graph) -> None:
+    inject_defaults(G, DEFAULTS)
+    register_sigma_callback(G)
+    register_metrics_callbacks(G)
+    register_trace(G)
+    _update_history(G)
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    G = build_graph(n=args.nodes, topology=args.topology, seed=args.seed)
+    _attach_callbacks(G)
+
+    if args.preset:
+        program = get_preset(args.preset)
+        play(G, program)
+    else:
+        steps = int(args.steps or 100)
+        for _ in range(steps):
+            step(G)
+
+    if args.save_history:
+        _save_json(args.save_history, G.graph.get("history", {}))
+
+    if args.summary:
+        tg = Tg_global(G, normalize=True)
+        lat = latency_series(G)
+        print("Top glifos por Tg:", glyph_top(G, k=5))
+        if lat["value"]:
+            print("Latencia media:", sum(lat["value"]) / max(1, len(lat["value"])) )
+    return 0
+
+
+def cmd_sequence(args: argparse.Namespace) -> int:
+    G = build_graph(n=args.nodes, topology=args.topology, seed=args.seed)
+    _attach_callbacks(G)
+
+    if args.preset:
+        program = get_preset(args.preset)
+    elif args.sequence_file:
+        program = _load_sequence(args.sequence_file)
+    else:
+        program = seq("A’L", "E’N", "I’L", block("O’Z", "Z’HIR", "I’L", repeat=1), "R’A", "SH’A")
+
+    play(G, program)
+
+    if args.save_history:
+        _save_json(args.save_history, G.graph.get("history", {}))
+    return 0
+
+
+def cmd_metrics(args: argparse.Namespace) -> int:
+    G = build_graph(n=args.nodes, topology=args.topology, seed=args.seed)
+    _attach_callbacks(G)
+    for _ in range(int(args.steps or 200)):
+        step(G)
+
+    tg = Tg_global(G, normalize=True)
+    lat = latency_series(G)
+    rose = sigma_rose(G)
+    glifo = glifogram_series(G)
+
+    out = {
+        "Tg_global": tg,
+        "latency_mean": (sum(lat["value"]) / max(1, len(lat["value"])) ) if lat["value"] else 0.0,
+        "rose": rose,
+        "glifogram": {k: v[:10] for k, v in glifo.items()},
+    }
+    if args.save:
+        _save_json(args.save, out)
+    else:
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="tnfr")
+    sub = p.add_subparsers(dest="cmd")
+
+    p_run = sub.add_parser("run", help="Correr escenario libre o preset y opcionalmente exportar history")
+    p_run.add_argument("--nodes", type=int, default=24)
+    p_run.add_argument("--topology", choices=["ring", "complete", "erdos"], default="ring")
+    p_run.add_argument("--steps", type=int, default=200)
+    p_run.add_argument("--seed", type=int, default=1)
+    p_run.add_argument("--preset", type=str, default=None)
+    p_run.add_argument("--save-history", dest="save_history", type=str, default=None)
+    p_run.add_argument("--summary", action="store_true")
+    p_run.set_defaults(func=cmd_run)
+
+    p_seq = sub.add_parser("sequence", help="Ejecutar una secuencia (preset o YAML/JSON)")
+    p_seq.add_argument("--nodes", type=int, default=24)
+    p_seq.add_argument("--topology", choices=["ring", "complete", "erdos"], default="ring")
+    p_seq.add_argument("--seed", type=int, default=1)
+    p_seq.add_argument("--preset", type=str, default=None)
+    p_seq.add_argument("--sequence-file", type=str, default=None)
+    p_seq.add_argument("--save-history", dest="save_history", type=str, default=None)
+    p_seq.set_defaults(func=cmd_sequence)
+
+    p_met = sub.add_parser("metrics", help="Correr breve y volcar métricas clave")
+    p_met.add_argument("--nodes", type=int, default=24)
+    p_met.add_argument("--topology", choices=["ring", "complete", "erdos"], default="ring")
+    p_met.add_argument("--steps", type=int, default=300)
+    p_met.add_argument("--seed", type=int, default=1)
+    p_met.add_argument("--save", type=str, default=None)
+    p_met.set_defaults(func=cmd_metrics)
+
+    args = p.parse_args(argv)
+    if not hasattr(args, "func"):
+        p.print_help()
+        return 1
+    return int(args.func(args))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

tnfr/constants.py

@@ -10,7 +10,7 @@ from typing import Dict, Any
 # -------------------------
 # Parámetros canónicos
 # -------------------------
-DEFAULTS: Dict[str, Any] = {
+DEFAULTS: Dict[str, Any] = {
     # Discretización
     "DT": 1.0,
 
@@ -147,22 +147,52 @@ DEFAULTS: Dict[str, Any] = {
         "dnfr_hi": 0.50, "dnfr_lo": 0.10,
         "accel_hi": 0.50, "accel_lo": 0.10
     },
-    # Callbacks Γ(R)
-    "CALLBACKS_STRICT": False,  # si True, un error en callback detiene; si False, se loguea y continúa
-}
+    # Callbacks Γ(R)
+    "GAMMA": {
+        "type": "none",  # 'none' | 'kuramoto_linear' | 'kuramoto_bandpass'
+        "beta": 0.0,
+        "R0": 0.0,
+    },
+    "CALLBACKS_STRICT": False,  # si True, un error en callback detiene; si False, se loguea y continúa
+}
+
+# Gramática glífica canónica
+DEFAULTS.setdefault("GRAMMAR_CANON", {
+    "enabled": True,                # activar la gramática canónica
+    "zhir_requires_oz_window": 3,   # cuántos pasos atrás buscamos O’Z
+    "zhir_dnfr_min": 0.05,          # si |ΔNFR|_norm < este valor, no permitimos Z’HIR sin O’Z
+    "thol_min_len": 2,
+    "thol_max_len": 6,
+    "thol_close_dnfr": 0.15,        # si el campo calma, cerramos con SH’A/NU’L
+    "si_high": 0.66,                # umbral para elegir NU’L vs SH’A al cerrar
+})
 
 
 # -------------------------
 # Utilidades
 # -------------------------
 
-def attach_defaults(G, override: bool = False) -> None:
-    """Escribe DEFAULTS en G.graph (sin sobreescribir si override=False)."""
-    G.graph.setdefault("_tnfr_defaults_attached", False)
-    for k, v in DEFAULTS.items():
-        if override or k not in G.graph:
-            G.graph[k] = v
-    G.graph["_tnfr_defaults_attached"] = True
+def attach_defaults(G, override: bool = False) -> None:
+    """Escribe DEFAULTS en G.graph (sin sobreescribir si override=False)."""
+    G.graph.setdefault("_tnfr_defaults_attached", False)
+    for k, v in DEFAULTS.items():
+        if override or k not in G.graph:
+            G.graph[k] = v
+    G.graph["_tnfr_defaults_attached"] = True
+
+
+def inject_defaults(G, defaults: Dict[str, Any] = DEFAULTS, override: bool = False) -> None:
+    """Alias de conveniencia para inyectar ``DEFAULTS`` en ``G.graph``.
+
+    Permite pasar un diccionario de *defaults* alternativo y mantiene la
+    semántica de ``attach_defaults`` existente. Si ``override`` es ``True`` se
+    sobreescriben valores ya presentes.
+    """
+    G.graph.setdefault("_tnfr_defaults_attached", False)
+    for k, v in defaults.items():
+        if override or k not in G.graph:
+            G.graph[k] = v
+    G.graph["_tnfr_defaults_attached"] = True
 
 
 def merge_overrides(G, **overrides) -> None:

tnfr/dynamics.py

@@ -13,11 +13,15 @@ Incluye:
 from __future__ import annotations
 from typing import Dict, Any, Iterable
 import math
-
-from observers import sincronía_fase, carga_glifica, orden_kuramoto, sigma_vector
-from operators import aplicar_remesh_si_estabilizacion_global
-from constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_SI, ALIAS_dEPI, ALIAS_D2EPI
-from helpers import (
+from collections import deque
+import networkx as nx
+
+from .observers import sincronía_fase, carga_glifica, orden_kuramoto, sigma_vector
+from .operators import aplicar_remesh_si_estabilizacion_global
+from .grammar import select_and_apply_with_grammar
+from .constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_SI, ALIAS_dEPI, ALIAS_D2EPI
+from .gamma import eval_gamma
+from .helpers import (
      clamp, clamp01, list_mean, phase_distance,
      _get_attr, _set_attr, media_vecinal, fase_media,
      invoke_callbacks, reciente_glifo
@@ -50,6 +54,7 @@ def _write_dnfr_metadata(G, *, weights: dict, hook_name: str, note: str | None =
 
 
 def default_compute_delta_nfr(G) -> None:
+    """Calcula ΔNFR mezclando gradientes de fase, EPI y νf según pesos."""
     w = G.graph.get("DNFR_WEIGHTS", DEFAULTS["DNFR_WEIGHTS"])  # dict
     w_phase = float(w.get("phase", 0.34))
     w_epi = float(w.get("epi", 0.33))
@@ -119,19 +124,49 @@ def dnfr_epi_vf_mixed(G) -> None:
 # Ecuación nodal
 # -------------------------
 
-def update_epi_via_nodal_equation(G, *, dt: float = None) -> None:
+def update_epi_via_nodal_equation(G, *, dt: float = None, t: float | None = None) -> None:
+    """Ecuación nodal TNFR.
+
+    Implementa la forma extendida de la ecuación nodal:
+        ∂EPI/∂t = νf · ΔNFR(t) + Γi(R)
+
+    Donde:
+      - EPI es la Estructura Primaria de Información del nodo.
+      - νf es la frecuencia estructural del nodo (Hz_str).
+      - ΔNFR(t) es el gradiente nodal (necesidad de reorganización),
+        típicamente una mezcla de componentes (p. ej. fase θ, EPI, νf).
+      - Γi(R) es el acoplamiento de red opcional en función del orden de Kuramoto R
+        (ver gamma.py), usado para modular la integración en red.
+
+    Referencias TNFR: ecuación nodal (manual), glosario νf/ΔNFR/EPI, operador Γ.
+    Efectos secundarios: cachea dEPI y actualiza EPI por integración explícita.
+    """
+    if not isinstance(G, (nx.Graph, nx.DiGraph, nx.MultiGraph, nx.MultiDiGraph)):
+        raise TypeError("G must be a networkx graph instance")
     if dt is None:
         dt = float(G.graph.get("DT", DEFAULTS["DT"]))
+    else:
+        if not isinstance(dt, (int, float)):
+            raise TypeError("dt must be a number")
+        if dt < 0:
+            raise ValueError("dt must be non-negative")
+        dt = float(dt)
+    if t is None:
+        t = float(G.graph.get("_t", 0.0))
+    else:
+        t = float(t)
     for n in G.nodes():
         nd = G.nodes[n]
         vf = _get_attr(nd, ALIAS_VF, 0.0)
         dnfr = _get_attr(nd, ALIAS_DNFR, 0.0)
         dEPI_dt_prev = _get_attr(nd, ALIAS_dEPI, 0.0)
         dEPI_dt = vf * dnfr
+        dEPI_dt += eval_gamma(G, n, t)
         epi = _get_attr(nd, ALIAS_EPI, 0.0) + dt * dEPI_dt
         _set_attr(nd, ALIAS_EPI, epi)
         _set_attr(nd, ALIAS_dEPI, dEPI_dt)
         _set_attr(nd, ALIAS_D2EPI, (dEPI_dt - dEPI_dt_prev) / dt if dt != 0 else 0.0)
+    G.graph["_t"] = t + dt
 
 
 # -------------------------
@@ -175,20 +210,30 @@ def coordinar_fase_global_vecinal(G, fuerza_global: float | None = None, fuerza_
     Si no se pasan fuerzas explícitas, adapta kG/kL según estado (disonante / transición / estable).
     Estado se decide por R (Kuramoto) y carga glífica disruptiva reciente.
     """
+    g = G.graph
+    defaults = DEFAULTS
     # 0) Si hay fuerzas explícitas, usar y salir del modo adaptativo
     if (fuerza_global is not None) or (fuerza_vecinal is not None):
-        kG = float(fuerza_global if fuerza_global is not None else G.graph.get("PHASE_K_GLOBAL", DEFAULTS["PHASE_K_GLOBAL"]))
-        kL = float(fuerza_vecinal if fuerza_vecinal is not None else G.graph.get("PHASE_K_LOCAL",  DEFAULTS["PHASE_K_LOCAL"]))
+        kG = float(
+            fuerza_global
+            if fuerza_global is not None
+            else g.get("PHASE_K_GLOBAL", defaults["PHASE_K_GLOBAL"])
+        )
+        kL = float(
+            fuerza_vecinal
+            if fuerza_vecinal is not None
+            else g.get("PHASE_K_LOCAL", defaults["PHASE_K_LOCAL"])
+        )
     else:
         # 1) Lectura de configuración
-        cfg = G.graph.get("PHASE_ADAPT", DEFAULTS.get("PHASE_ADAPT", {}))
-        kG = float(G.graph.get("PHASE_K_GLOBAL", DEFAULTS["PHASE_K_GLOBAL"]))
-        kL = float(G.graph.get("PHASE_K_LOCAL",  DEFAULTS["PHASE_K_LOCAL"]))
+        cfg = g.get("PHASE_ADAPT", defaults.get("PHASE_ADAPT", {}))
+        kG = float(g.get("PHASE_K_GLOBAL", defaults["PHASE_K_GLOBAL"]))
+        kL = float(g.get("PHASE_K_LOCAL", defaults["PHASE_K_LOCAL"]))
 
         if bool(cfg.get("enabled", False)):
             # 2) Métricas actuales (no dependemos de history)
             R = orden_kuramoto(G)
-            win = int(G.graph.get("GLYPH_LOAD_WINDOW", DEFAULTS["GLYPH_LOAD_WINDOW"]))
+            win = int(g.get("GLYPH_LOAD_WINDOW", defaults["GLYPH_LOAD_WINDOW"]))
             dist = carga_glifica(G, window=win)
             disr = float(dist.get("_disruptivos", 0.0)) if dist else 0.0
 
@@ -216,7 +261,9 @@ def coordinar_fase_global_vecinal(G, fuerza_global: float | None = None, fuerza_
                 kG_t = 0.5 * (kG_min + kG_max)
                 kL_t = 0.5 * (kL_min + kL_max)
 
-            up = float(cfg.get("up", 0.10)); down = float(cfg.get("down", 0.07))
+            up = float(cfg.get("up", 0.10))
+            down = float(cfg.get("down", 0.07))
+
             def _step(curr, target, mn, mx):
                 gain = up if target > curr else down
                 nxt = curr + gain * (target - curr)
@@ -226,14 +273,19 @@ def coordinar_fase_global_vecinal(G, fuerza_global: float | None = None, fuerza_
             kL = _step(kL, kL_t, kL_min, kL_max)
 
             # 5) Persistir en G.graph y log de serie
-            G.graph["PHASE_K_GLOBAL"] = kG
-            G.graph["PHASE_K_LOCAL"]  = kL
-            hist = G.graph.setdefault("history", {})
-            hist.setdefault("phase_kG", []).append(float(kG))
-            hist.setdefault("phase_kL", []).append(float(kL))
-            hist.setdefault("phase_state", []).append(state)
-            hist.setdefault("phase_R", []).append(float(R))
-            hist.setdefault("phase_disr", []).append(float(disr))
+            g["PHASE_K_GLOBAL"] = kG
+            g["PHASE_K_LOCAL"] = kL
+            hist = g.setdefault("history", {})
+            hist_kG = hist.setdefault("phase_kG", [])
+            hist_kL = hist.setdefault("phase_kL", [])
+            hist_state = hist.setdefault("phase_state", [])
+            hist_R = hist.setdefault("phase_R", [])
+            hist_disr = hist.setdefault("phase_disr", [])
+            hist_kG.append(float(kG))
+            hist_kL.append(float(kL))
+            hist_state.append(state)
+            hist_R.append(float(R))
+            hist_disr.append(float(disr))
 
     # 6) Fase GLOBAL (centroide) para empuje
     X = list(math.cos(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes())
@@ -394,7 +446,7 @@ def step(G, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool
 
     # 2) (opcional) Si
     if use_Si:
-        from helpers import compute_Si
+        from .helpers import compute_Si
         compute_Si(G, inplace=True)
 
     # 2b) Normalizadores para selector paramétrico (por paso)
@@ -403,11 +455,15 @@ def step(G, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool
     # 3) Selección glífica + aplicación
     if apply_glyphs:
         selector = G.graph.get("glyph_selector", default_glyph_selector)
-        from operators import aplicar_glifo
+        from .operators import aplicar_glifo
         window = int(G.graph.get("GLYPH_HYSTERESIS_WINDOW", DEFAULTS["GLYPH_HYSTERESIS_WINDOW"]))
+        use_canon = bool(G.graph.get("GRAMMAR_CANON", DEFAULTS.get("GRAMMAR_CANON", {})).get("enabled", False))
         for n in G.nodes():
-            g = selector(G, n)
-            aplicar_glifo(G, n, g, window=window)
+            if use_canon:
+                select_and_apply_with_grammar(G, n, selector, window)
+            else:
+                g = selector(G, n)
+                aplicar_glifo(G, n, g, window=window)
 
     # 4) Ecuación nodal
     update_epi_via_nodal_equation(G, dt=dt)
@@ -422,13 +478,13 @@ def step(G, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool
     # 7) Observadores ligeros
     _update_history(G)
     # dynamics.py — dentro de step(), justo antes del punto 8)
-    epi_hist = G.graph.setdefault("_epi_hist", [])
-    epi_hist.append({n: _get_attr(G.nodes[n], ALIAS_EPI, 0.0) for n in G.nodes()})
-    # recorta el buffer para que no crezca sin límite
     tau = int(G.graph.get("REMESH_TAU", DEFAULTS["REMESH_TAU"]))
-    maxlen = max(2*tau + 5, 64)
-    if len(epi_hist) > maxlen:
-        del epi_hist[:-maxlen]
+    maxlen = max(2 * tau + 5, 64)
+    epi_hist = G.graph.get("_epi_hist")
+    if not isinstance(epi_hist, deque) or epi_hist.maxlen != maxlen:
+        epi_hist = deque(list(epi_hist or [])[-maxlen:], maxlen=maxlen)
+        G.graph["_epi_hist"] = epi_hist
+    epi_hist.append({n: _get_attr(G.nodes[n], ALIAS_EPI, 0.0) for n in G.nodes()})
 
     # 8) RE’MESH condicionado
     aplicar_remesh_si_estabilizacion_global(G)

tnfr/gamma.py

@@ -0,0 +1,91 @@
+"""gamma.py — TNFR canónica
+
+Γi(R): acoplamientos de red para la ecuación nodal extendida
+    ∂EPI/∂t = νf · ΔNFR(t) + Γi(R)
+
+Provee:
+- kuramoto_R_psi(G): (R, ψ) orden de Kuramoto en la red
+- GAMMA_REGISTRY: registro de acoplamientos canónicos
+- eval_gamma(G, node, t): evalúa Γ para cada nodo según G.graph['GAMMA']
+"""
+from __future__ import annotations
+from typing import Dict, Any, Tuple
+import math
+import cmath
+
+from .constants import ALIAS_THETA
+
+
+def _get_attr(nd: Dict[str, Any], aliases, default: float = 0.0) -> float:
+    """Obtiene el primer atributo presente en nd según aliases."""
+    for k in aliases:
+        if k in nd:
+            return nd[k]
+    return default
+
+
+def kuramoto_R_psi(G) -> Tuple[float, float]:
+    """Devuelve (R, ψ) del orden de Kuramoto usando θ de todos los nodos."""
+    acc = 0 + 0j
+    n = 0
+    for node in G.nodes():
+        nd = G.nodes[node]
+        th = _get_attr(nd, ALIAS_THETA, 0.0)
+        acc += cmath.exp(1j * th)
+        n += 1
+    if n == 0:
+        return 0.0, 0.0
+    z = acc / n
+    return abs(z), math.atan2(z.imag, z.real)
+
+
+# -----------------
+# Γi(R) canónicos
+# -----------------
+
+
+def gamma_none(G, node, t, cfg: Dict[str, Any]) -> float:
+    return 0.0
+
+
+def gamma_kuramoto_linear(G, node, t, cfg: Dict[str, Any]) -> float:
+    """Acoplamiento lineal de Kuramoto para Γi(R).
+
+    Fórmula: Γ = β · (R - R0) · cos(θ_i - ψ)
+      - R ∈ [0,1] es el orden global de fase.
+      - ψ es la fase media (dirección de coordinación).
+      - β, R0 son parámetros (ganancia/umbral).
+
+    Uso: refuerza integración cuando la red ya exhibe coherencia de fase (R>R0).
+    """
+    beta = float(cfg.get("beta", 0.0))
+    R0 = float(cfg.get("R0", 0.0))
+    R, psi = kuramoto_R_psi(G)
+    th_i = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+    return beta * (R - R0) * math.cos(th_i - psi)
+
+
+def gamma_kuramoto_bandpass(G, node, t, cfg: Dict[str, Any]) -> float:
+    """Γ = β · R(1-R) · sign(cos(θ_i - ψ))"""
+    beta = float(cfg.get("beta", 0.0))
+    R, psi = kuramoto_R_psi(G)
+    th_i = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+    sgn = 1.0 if math.cos(th_i - psi) >= 0.0 else -1.0
+    return beta * R * (1.0 - R) * sgn
+
+
+GAMMA_REGISTRY = {
+    "none": gamma_none,
+    "kuramoto_linear": gamma_kuramoto_linear,
+    "kuramoto_bandpass": gamma_kuramoto_bandpass,
+}
+
+
+def eval_gamma(G, node, t) -> float:
+    """Evalúa Γi para `node` según la especificación en G.graph['GAMMA']."""
+    spec = G.graph.get("GAMMA", {"type": "none"})
+    fn = GAMMA_REGISTRY.get(spec.get("type", "none"), gamma_none)
+    try:
+        return float(fn(G, node, t, spec))
+    except Exception:
+        return 0.0