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

tnfr/dynamics.py

@@ -11,23 +11,29 @@ Incluye:
 - default_glyph_selector, step, run
 """
 from __future__ import annotations
-from typing import Dict, Any, Iterable
+from typing import Dict, Any, Iterable, Literal
 import math
 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 .grammar import (
+    enforce_canonical_grammar,
+    on_applied_glifo,
+    AL,
+    EN,
+)
 from .constants import (
     DEFAULTS,
     ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_SI,
     ALIAS_dEPI, ALIAS_D2EPI, ALIAS_dVF, ALIAS_D2VF, ALIAS_dSI,
+    ALIAS_EPI_KIND,
 )
 from .gamma import eval_gamma
 from .helpers import (
      clamp, clamp01, list_mean, phase_distance,
-     _get_attr, _set_attr, media_vecinal, fase_media,
+     _get_attr, _set_attr, _get_attr_str, _set_attr_str, media_vecinal, fase_media,
      invoke_callbacks, reciente_glifo
 )
 
@@ -36,20 +42,21 @@ from .helpers import (
 # -------------------------
 
 def _write_dnfr_metadata(G, *, weights: dict, hook_name: str, note: str | None = None) -> None:
-    """Escribe en G.graph un bloque _DNFR_META con la mezcla y el nombre del hook."""
-    w_phase = float(weights.get("phase", 0.0))
-    w_epi   = float(weights.get("epi",   0.0))
-    w_vf    = float(weights.get("vf",    0.0))
-    s = w_phase + w_epi + w_vf
-    if s <= 0:
-        w_phase = w_epi = w_vf = 1/3
-        s = 1.0
+    """Escribe en G.graph un bloque _DNFR_META con la mezcla y el nombre del hook.
+
+    `weights` puede incluir componentes arbitrarias (phase/epi/vf/topo/etc.)."""
+    total = sum(float(v) for v in weights.values())
+    if total <= 0:
+        # si no hay pesos, normalizamos a componentes iguales
+        n = max(1, len(weights))
+        weights = {k: 1.0 / n for k in weights}
+        total = 1.0
     meta = {
         "hook": hook_name,
         "weights_raw": dict(weights),
-        "weights_norm": {"phase": w_phase/s, "epi": w_epi/s, "vf": w_vf/s},
-        "components": [k for k, v in {"phase":w_phase, "epi":w_epi, "vf":w_vf}.items() if v != 0],
-        "doc": "ΔNFR = w_phase·g_phase + w_epi·g_epi + w_vf·g_vf",
+        "weights_norm": {k: float(v) / total for k, v in weights.items()},
+        "components": [k for k, v in weights.items() if float(v) != 0.0],
+        "doc": "ΔNFR = Σ w_i·g_i",
     }
     if note:
         meta["note"] = str(note)
@@ -58,26 +65,35 @@ 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."""
+    """Calcula ΔNFR mezclando gradientes de fase, EPI, νf y un término topológico."""
     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))
     w_vf = float(w.get("vf", 0.33))
-    s = w_phase + w_epi + w_vf
+    w_topo = float(w.get("topo", 0.0))
+    s = w_phase + w_epi + w_vf + w_topo
     if s <= 0:
         w_phase = w_epi = w_vf = 1/3
+        w_topo = 0.0
+        s = 1.0
     else:
-        w_phase, w_epi, w_vf = w_phase/s, w_epi/s, w_vf/s
+        w_phase, w_epi, w_vf, w_topo = (w_phase/s, w_epi/s, w_vf/s, w_topo/s)
 
     # Documentar mezcla y hook activo
-    _write_dnfr_metadata(G, weights={"phase":w_phase, "epi":w_epi, "vf":w_vf}, hook_name="default_compute_delta_nfr")
- 
+    _write_dnfr_metadata(
+        G,
+        weights={"phase": w_phase, "epi": w_epi, "vf": w_vf, "topo": w_topo},
+        hook_name="default_compute_delta_nfr",
+    )
+
+    degs = dict(G.degree()) if w_topo != 0 else None
+
     for n in G.nodes():
         nd = G.nodes[n]
         th_i = _get_attr(nd, ALIAS_THETA, 0.0)
         th_bar = fase_media(G, n)
         # Gradiente de fase: empuja hacia la fase media (signo envuelto)
-        g_phase = - ( (th_i - th_bar + math.pi) % (2*math.pi) - math.pi ) / math.pi  # ~[-1,1]
+        g_phase = -((th_i - th_bar + math.pi) % (2 * math.pi) - math.pi) / math.pi  # ~[-1,1]
 
         epi_i = _get_attr(nd, ALIAS_EPI, 0.0)
         epi_bar = media_vecinal(G, n, ALIAS_EPI, default=epi_i)
@@ -87,7 +103,14 @@ def default_compute_delta_nfr(G) -> None:
         vf_bar = media_vecinal(G, n, ALIAS_VF, default=vf_i)
         g_vf = (vf_bar - vf_i)
 
-        dnfr = w_phase*g_phase + w_epi*g_epi + w_vf*g_vf
+        if w_topo != 0 and degs is not None:
+            deg_i = float(degs.get(n, 0))
+            deg_bar = list_mean(degs.get(v, deg_i) for v in G.neighbors(n)) if G.degree(n) else deg_i
+            g_topo = deg_bar - deg_i
+        else:
+            g_topo = 0.0
+
+        dnfr = w_phase * g_phase + w_epi * g_epi + w_vf * g_vf + w_topo * g_topo
         _set_attr(nd, ALIAS_DNFR, dnfr)
 
 def set_delta_nfr_hook(G, func, *, name: str | None = None, note: str | None = None) -> None:
@@ -107,9 +130,9 @@ def dnfr_phase_only(G) -> None:
         nd = G.nodes[n]
         th_i = _get_attr(nd, ALIAS_THETA, 0.0)
         th_bar = fase_media(G, n)
-        g_phase = - ( (th_i - th_bar + math.pi) % (2*math.pi) - math.pi ) / math.pi
+        g_phase = -((th_i - th_bar + math.pi) % (2 * math.pi) - math.pi) / math.pi
         _set_attr(nd, ALIAS_DNFR, g_phase)
-    _write_dnfr_metadata(G, weights={"phase":1.0, "epi":0.0, "vf":0.0}, hook_name="dnfr_phase_only", note="Hook de ejemplo.")
+    _write_dnfr_metadata(G, weights={"phase": 1.0}, hook_name="dnfr_phase_only", note="Hook de ejemplo.")
 
 def dnfr_epi_vf_mixed(G) -> None:
     """Ejemplo: ΔNFR sin fase, mezclando EPI y νf."""
@@ -124,11 +147,40 @@ def dnfr_epi_vf_mixed(G) -> None:
         _set_attr(nd, ALIAS_DNFR, 0.5*g_epi + 0.5*g_vf)
     _write_dnfr_metadata(G, weights={"phase":0.0, "epi":0.5, "vf":0.5}, hook_name="dnfr_epi_vf_mixed", note="Hook de ejemplo.")
 
+
+def dnfr_laplacian(G) -> None:
+    """Gradiente topológico explícito usando Laplaciano sobre EPI y νf."""
+    wE = float(G.graph.get("DNFR_WEIGHTS", {}).get("epi", 0.33))
+    wV = float(G.graph.get("DNFR_WEIGHTS", {}).get("vf", 0.33))
+    for n in G.nodes():
+        nd = G.nodes[n]
+        epi = _get_attr(nd, ALIAS_EPI, 0.0)
+        vf = _get_attr(nd, ALIAS_VF, 0.0)
+        neigh = list(G.neighbors(n))
+        deg = len(neigh) or 1
+        epi_bar = sum(_get_attr(G.nodes[v], ALIAS_EPI, epi) for v in neigh) / deg
+        vf_bar = sum(_get_attr(G.nodes[v], ALIAS_VF, vf) for v in neigh) / deg
+        g_epi = epi_bar - epi
+        g_vf = vf_bar - vf
+        _set_attr(nd, ALIAS_DNFR, wE * g_epi + wV * g_vf)
+    _write_dnfr_metadata(
+        G,
+        weights={"epi": wE, "vf": wV},
+        hook_name="dnfr_laplacian",
+        note="Gradiente topológico",
+    )
+
 # -------------------------
 # Ecuación nodal
 # -------------------------
 
-def update_epi_via_nodal_equation(G, *, dt: float = None, t: float | None = None) -> None:
+def update_epi_via_nodal_equation(
+    G,
+    *,
+    dt: float = None,
+    t: float | None = None,
+    method: Literal["euler", "rk4"] | None = None,
+) -> None:
     """Ecuación nodal TNFR.
 
     Implementa la forma extendida de la ecuación nodal:
@@ -159,18 +211,50 @@ def update_epi_via_nodal_equation(G, *, dt: float = None, t: float | None = 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
+
+    method = (method or G.graph.get("INTEGRATOR_METHOD", DEFAULTS.get("INTEGRATOR_METHOD", "euler"))).lower()
+    dt_min = float(G.graph.get("DT_MIN", DEFAULTS.get("DT_MIN", 0.0)))
+    if dt_min > 0 and dt > dt_min:
+        steps = int(math.ceil(dt / dt_min))
+    else:
+        steps = 1
+    dt_step = dt / steps if steps else 0.0
+
+    t_local = t
+    for _ in range(steps):
+        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)
+            epi_i = _get_attr(nd, ALIAS_EPI, 0.0)
+
+            def _f(time: float) -> float:
+                return vf * dnfr + eval_gamma(G, n, time)
+
+            if method == "rk4":
+                k1 = _f(t_local)
+                k2 = _f(t_local + dt_step / 2.0)
+                k3 = _f(t_local + dt_step / 2.0)
+                k4 = _f(t_local + dt_step)
+                epi = epi_i + (dt_step / 6.0) * (k1 + 2 * k2 + 2 * k3 + k4)
+                dEPI_dt = k4
+            else:
+                if method != "euler":
+                    raise ValueError("method must be 'euler' or 'rk4'")
+                dEPI_dt = _f(t_local)
+                epi = epi_i + dt_step * dEPI_dt
+
+            epi_kind = _get_attr_str(nd, ALIAS_EPI_KIND, "")
+            _set_attr(nd, ALIAS_EPI, epi)
+            if epi_kind:
+                _set_attr_str(nd, ALIAS_EPI_KIND, epi_kind)
+            _set_attr(nd, ALIAS_dEPI, dEPI_dt)
+            _set_attr(nd, ALIAS_D2EPI, (dEPI_dt - dEPI_dt_prev) / dt_step if dt_step != 0 else 0.0)
+
+        t_local += dt_step
+
+    G.graph["_t"] = t_local
 
 
 # -------------------------
@@ -188,7 +272,7 @@ def aplicar_dnfr_campo(G, w_theta=None, w_epi=None, w_vf=None) -> None:
 
 
 def integrar_epi_euler(G, dt: float | None = None) -> None:
-    update_epi_via_nodal_equation(G, dt=dt)
+    update_epi_via_nodal_equation(G, dt=dt, method="euler")
 
 
 def aplicar_clamps_canonicos(nd: Dict[str, Any], G=None, node=None) -> None:
@@ -326,6 +410,40 @@ def coordinar_fase_global_vecinal(G, fuerza_global: float | None = None, fuerza_
         dL = ((thL - th + math.pi) % (2*math.pi) - math.pi)
         _set_attr(nd, ALIAS_THETA, th + kG*dG + kL*dL)
 
+# -------------------------
+# Adaptación de νf por coherencia
+# -------------------------
+
+def adaptar_vf_por_coherencia(G) -> None:
+    """Ajusta νf hacia la media vecinal en nodos con estabilidad sostenida."""
+    tau = int(G.graph.get("VF_ADAPT_TAU", DEFAULTS.get("VF_ADAPT_TAU", 5)))
+    mu = float(G.graph.get("VF_ADAPT_MU", DEFAULTS.get("VF_ADAPT_MU", 0.1)))
+    eps_dnfr = float(G.graph.get("EPS_DNFR_STABLE", DEFAULTS["EPS_DNFR_STABLE"]))
+    thr_sel = G.graph.get("SELECTOR_THRESHOLDS", DEFAULTS.get("SELECTOR_THRESHOLDS", {}))
+    thr_def = G.graph.get("GLYPH_THRESHOLDS", DEFAULTS.get("GLYPH_THRESHOLDS", {"hi": 0.66}))
+    si_hi = float(thr_sel.get("si_hi", thr_def.get("hi", 0.66)))
+    vf_min = float(G.graph.get("VF_MIN", DEFAULTS["VF_MIN"]))
+    vf_max = float(G.graph.get("VF_MAX", DEFAULTS["VF_MAX"]))
+
+    updates = {}
+    for n in G.nodes():
+        nd = G.nodes[n]
+        Si = _get_attr(nd, ALIAS_SI, 0.0)
+        dnfr = abs(_get_attr(nd, ALIAS_DNFR, 0.0))
+        if Si >= si_hi and dnfr <= eps_dnfr:
+            nd["stable_count"] = nd.get("stable_count", 0) + 1
+        else:
+            nd["stable_count"] = 0
+            continue
+
+        if nd["stable_count"] >= tau:
+            vf = _get_attr(nd, ALIAS_VF, 0.0)
+            vf_bar = media_vecinal(G, n, ALIAS_VF, default=vf)
+            updates[n] = vf + mu * (vf_bar - vf)
+
+    for n, vf_new in updates.items():
+        _set_attr(G.nodes[n], ALIAS_VF, clamp(vf_new, vf_min, vf_max))
+
 # -------------------------
 # Selector glífico por defecto
 # -------------------------
@@ -489,21 +607,45 @@ def step(G, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool
     # 2b) Normalizadores para selector paramétrico (por paso)
     _norms_para_selector(G)  # no molesta si luego se usa el selector por defecto
 
-    # 3) Selección glífica + aplicación
+    # 3) Selección glífica + aplicación (con lags obligatorios A’L/E’N)
     if apply_glyphs:
         selector = G.graph.get("glyph_selector", default_glyph_selector)
         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))
+
+        al_max = int(G.graph.get("AL_MAX_LAG", DEFAULTS["AL_MAX_LAG"]))
+        en_max = int(G.graph.get("EN_MAX_LAG", DEFAULTS["EN_MAX_LAG"]))
+        h_al = _hist0.setdefault("since_AL", {})
+        h_en = _hist0.setdefault("since_EN", {})
+
         for n in G.nodes():
-            if use_canon:
-                select_and_apply_with_grammar(G, n, selector, window)
+            h_al[n] = int(h_al.get(n, 0)) + 1
+            h_en[n] = int(h_en.get(n, 0)) + 1
+
+            if h_al[n] > al_max:
+                g = AL
+            elif h_en[n] > en_max:
+                g = EN
             else:
                 g = selector(G, n)
-                aplicar_glifo(G, n, g, window=window)
+                if use_canon:
+                    g = enforce_canonical_grammar(G, n, g)
+
+            aplicar_glifo(G, n, g, window=window)
+            if use_canon:
+                on_applied_glifo(G, n, g)
+
+            if g == AL:
+                h_al[n] = 0
+                h_en[n] = min(h_en[n], en_max)
+            elif g == EN:
+                h_en[n] = 0
 
     # 4) Ecuación nodal
-    update_epi_via_nodal_equation(G, dt=dt)
+    _dt = float(G.graph.get("DT", DEFAULTS["DT"])) if dt is None else float(dt)
+    method = G.graph.get("INTEGRATOR_METHOD", DEFAULTS.get("INTEGRATOR_METHOD", "euler"))
+    update_epi_via_nodal_equation(G, dt=_dt, method=method)
 
     # 5) Clamps
     for n in G.nodes():
@@ -512,6 +654,9 @@ def step(G, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool
     # 6) Coordinación de fase
     coordinar_fase_global_vecinal(G, None, None)
 
+    # 6b) Adaptación de νf por coherencia
+    adaptar_vf_por_coherencia(G)
+
     # 7) Observadores ligeros
     _update_history(G)
     # dynamics.py — dentro de step(), justo antes del punto 8)
@@ -528,6 +673,10 @@ def step(G, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool
     # 8) RE’MESH condicionado
     aplicar_remesh_si_estabilizacion_global(G)
 
+    # 8b) Validadores de invariantes
+    from .validators import run_validators
+    run_validators(G)
+
     # Contexto final (últimas métricas del paso)
     h = G.graph.get("history", {})
     ctx = {"step": step_idx}

tnfr/gamma.py

@@ -92,11 +92,28 @@ def gamma_kuramoto_tanh(G, node, t, cfg: Dict[str, Any]) -> float:
     return beta * math.tanh(k * (R - R0)) * math.cos(th_i - psi)
 
 
+def gamma_harmonic(G, node, t, cfg: Dict[str, Any]) -> float:
+    """Forzamiento armónico coherente con el campo global de fase.
+
+    Fórmula: Γ = β · sin(ω·t + φ) · cos(θ_i - ψ)
+      - β: ganancia del acoplamiento
+      - ω: frecuencia angular del forzante
+      - φ: fase inicial del forzante
+    """
+    beta = float(cfg.get("beta", 0.0))
+    omega = float(cfg.get("omega", 1.0))
+    phi = float(cfg.get("phi", 0.0))
+    R, psi = kuramoto_R_psi(G)
+    th = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+    return beta * math.sin(omega * t + phi) * math.cos(th - psi)
+
+
 GAMMA_REGISTRY = {
     "none": gamma_none,
     "kuramoto_linear": gamma_kuramoto_linear,
     "kuramoto_bandpass": gamma_kuramoto_bandpass,
     "kuramoto_tanh": gamma_kuramoto_tanh,
+    "harmonic": gamma_harmonic,
 }
 
 

tnfr/helpers.py

@@ -14,7 +14,7 @@ try:
 except Exception:  # pragma: no cover
     nx = None  # type: ignore
 
-from .constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_SI
+from .constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_SI, ALIAS_EPI_KIND
 
 # -------------------------
 # Utilidades numéricas
@@ -76,6 +76,24 @@ def _set_attr(d, aliases, value: float) -> None:
             return
     d[next(iter(aliases))] = float(value)
 
+
+def _get_attr_str(d: Dict[str, Any], aliases: Iterable[str], default: str = "") -> str:
+    for k in aliases:
+        if k in d:
+            try:
+                return str(d[k])
+            except Exception:
+                continue
+    return str(default)
+
+
+def _set_attr_str(d, aliases, value: str) -> None:
+    for k in aliases:
+        if k in d:
+            d[k] = str(value)
+            return
+    d[next(iter(aliases))] = str(value)
+
 # -------------------------
 # Estadísticos vecinales
 # -------------------------
@@ -111,18 +129,14 @@ def push_glifo(nd: Dict[str, Any], glifo: str, window: int) -> None:
 
 
 def reciente_glifo(nd: Dict[str, Any], glifo: str, ventana: int) -> bool:
-    """Indica si ``glifo`` apareció en las últimas ``ventana`` emisiones."""
+    """Indica si ``glifo`` apareció en las últimas ``ventana`` emisiones"""
     hist = nd.get("hist_glifos")
-    if not hist:
-        return False
     gl = str(glifo)
-    for g in reversed(hist):
-        if g == gl:
-            return True
-        ventana -= 1
-        if ventana <= 0:
-            break
-    return False
+    from itertools import islice
+    if hist and any(g == gl for g in islice(reversed(hist), ventana)):
+        return True
+    # fallback al glifo dominante actual
+    return _get_attr_str(nd, ALIAS_EPI_KIND, "") == gl
 
 # -------------------------
 # Utilidades de historial global
@@ -130,18 +144,19 @@ def reciente_glifo(nd: Dict[str, Any], glifo: str, ventana: int) -> bool:
 
 def ensure_history(G) -> Dict[str, Any]:
     """Garantiza G.graph['history'] y la devuelve."""
-    if "history" not in G.graph:
-        G.graph["history"] = {}
-    return G.graph["history"]
+    return G.graph.setdefault("history", {})
 
 
 def last_glifo(nd: Dict[str, Any]) -> str | None:
     """Retorna el glifo más reciente del nodo o ``None``."""
+    kind = _get_attr_str(nd, ALIAS_EPI_KIND, "")
+    if kind:
+        return kind
     hist = nd.get("hist_glifos")
     if not hist:
         return None
     try:
-        return list(hist)[-1]
+        return hist[-1]
     except Exception:
         return None
 
@@ -223,12 +238,9 @@ def compute_Si(G, *, inplace: bool = True) -> Dict[Any, float]:
     G.graph["_Si_weights"] = {"alpha": alpha, "beta": beta, "gamma": gamma}
     G.graph["_Si_sensitivity"] = {"dSi_dvf_norm": alpha, "dSi_ddisp_fase": -beta, "dSi_ddnfr_norm": -gamma}
 
-    # Normalización de νf en red
-    vfs = [abs(_get_attr(G.nodes[n], ALIAS_VF, 0.0)) for n in G.nodes()]
-    vfmax = max(vfs) if vfs else 1.0
-    # Normalización de ΔNFR
-    dnfrs = [abs(_get_attr(G.nodes[n], ALIAS_DNFR, 0.0)) for n in G.nodes()]
-    dnfrmax = max(dnfrs) if dnfrs else 1.0
+    # Normalización de νf y ΔNFR en red
+    vfmax = max((abs(_get_attr(G.nodes[n], ALIAS_VF, 0.0)) for n in G.nodes()), default=1.0)
+    dnfrmax = max((abs(_get_attr(G.nodes[n], ALIAS_DNFR, 0.0)) for n in G.nodes()), default=1.0)
 
     out: Dict[Any, float] = {}
     for n in G.nodes():