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

tnfr/helpers.py

@@ -4,7 +4,7 @@ helpers.py — TNFR canónica
 Utilidades transversales + cálculo de Índice de sentido (Si).
 """
 from __future__ import annotations
-from typing import Iterable, Dict, Any, Tuple, List
+from typing import Iterable, Dict, Any
 import math
 from collections import deque
 from statistics import fmean, StatisticsError
@@ -21,19 +21,23 @@ from .constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, A
 # -------------------------
 
 def clamp(x: float, a: float, b: float) -> float:
+    """Constriñe ``x`` al intervalo cerrado [a, b]."""
     return a if x < a else b if x > b else x
 
 
 def clamp_abs(x: float, m: float) -> float:
+    """Limita ``x`` al rango simétrico [-m, m] usando ``abs(m)``."""
     m = abs(m)
     return clamp(x, -m, m)
 
 
 def clamp01(x: float) -> float:
+    """Ataja ``x`` a la banda [0, 1]."""
     return clamp(x, 0.0, 1.0)
 
 
 def list_mean(xs: Iterable[float], default: float = 0.0) -> float:
+    """Promedio aritmético o ``default`` si ``xs`` está vacío."""
     try:
         return fmean(xs)
     except StatisticsError:
@@ -77,16 +81,14 @@ def _set_attr(d, aliases, value: float) -> None:
 # -------------------------
 
 def media_vecinal(G, n, aliases: Iterable[str], default: float = 0.0) -> float:
-    vals: List[float] = []
-    for v in G.neighbors(n):
-        vals.append(_get_attr(G.nodes[v], aliases, default))
+    """Media del atributo indicado por ``aliases`` en los vecinos de ``n``."""
+    vals = (_get_attr(G.nodes[v], aliases, default) for v in G.neighbors(n))
     return list_mean(vals, default)
 
 
 def fase_media(G, n) -> float:
     """Promedio circular de las fases de los vecinos."""
-    x = 0.0
-    y = 0.0
+    x = y = 0.0
     count = 0
     for v in G.neighbors(n):
         th = _get_attr(G.nodes[v], ALIAS_THETA, 0.0)
@@ -95,7 +97,7 @@ def fase_media(G, n) -> float:
         count += 1
     if count == 0:
         return _get_attr(G.nodes[n], ALIAS_THETA, 0.0)
-    return math.atan2(y / max(1, count), x / max(1, count))
+    return math.atan2(y / count, x / count)
 
 
 # -------------------------
@@ -103,16 +105,24 @@ def fase_media(G, n) -> float:
 # -------------------------
 
 def push_glifo(nd: Dict[str, Any], glifo: str, window: int) -> None:
+    """Añade ``glifo`` al historial del nodo con tamaño máximo ``window``."""
     hist = nd.setdefault("hist_glifos", deque(maxlen=window))
     hist.append(str(glifo))
 
 
 def reciente_glifo(nd: Dict[str, Any], glifo: str, ventana: int) -> bool:
+    """Indica si ``glifo`` apareció en las últimas ``ventana`` emisiones."""
     hist = nd.get("hist_glifos")
     if not hist:
         return False
-    last = list(hist)[-ventana:]
-    return str(glifo) in last
+    gl = str(glifo)
+    for g in reversed(hist):
+        if g == gl:
+            return True
+        ventana -= 1
+        if ventana <= 0:
+            break
+    return False
 
 # -------------------------
 # Callbacks Γ(R)
@@ -130,10 +140,26 @@ def _ensure_callbacks(G):
         cbs.setdefault(k, [])
     return cbs
 
-def register_callback(G, event: str, func):
-    """Registra un callback en G.graph['callbacks'][event]. Firma: func(G, ctx) -> None"""
+def register_callback(
+    G,
+    event: str | None = None,
+    func=None,
+    *,
+    when: str | None = None,
+    name: str | None = None,
+):
+    """Registra ``func`` como callback del ``event`` indicado.
+
+    Permite tanto la forma posicional ``register_callback(G, "after_step", fn)``
+    como la forma con palabras clave ``register_callback(G, when="after_step", func=fn)``.
+    El parámetro ``name`` se acepta por compatibilidad pero actualmente no se
+    utiliza.
+    """
+    event = event or when
     if event not in ("before_step", "after_step", "on_remesh"):
         raise ValueError(f"Evento desconocido: {event}")
+    if func is None:
+        raise TypeError("func es obligatorio")
     cbs = _ensure_callbacks(G)
     cbs[event].append(func)
     return func

tnfr/main.py

@@ -1,7 +1,11 @@
 from __future__ import annotations
-import argparse, sys
-import networkx as nx
-from . import preparar_red, run, __version__
+import argparse, sys
+import networkx as nx
+from . import preparar_red, run, __version__
+from .constants import merge_overrides, attach_defaults
+from .sense import register_sigma_callback
+from .metrics import register_metrics_callbacks
+from .trace import register_trace
 
 def main(argv: list[str] | None = None) -> None:
     p = argparse.ArgumentParser(
@@ -15,13 +19,19 @@ def main(argv: list[str] | None = None) -> None:
     p.add_argument("--observer", action="store_true", help="adjunta observador estándar")
     args = p.parse_args(argv)
 
-    if args.version:
-        print(__version__)
-        return
-
-    G = nx.erdos_renyi_graph(args.n, args.p)
-    preparar_red(G, ATTACH_STD_OBSERVER=bool(args.observer))
-    run(G, args.steps)
+    if args.version:
+        print(__version__)
+        return
+
+    G = nx.erdos_renyi_graph(args.n, args.p)
+    preparar_red(G, ATTACH_STD_OBSERVER=bool(args.observer))
+    attach_defaults(G)
+    register_sigma_callback(G)
+    register_metrics_callbacks(G)
+    register_trace(G)
+    # Ejemplo: activar Γi(R) lineal con β=0.2 y R0=0.5
+    merge_overrides(G, GAMMA={"type": "kuramoto_linear", "beta": 0.2, "R0": 0.5})
+    run(G, args.steps)
 
     h = G.graph.get("history", {})
     C = h.get("C_steps", [])[-1] if h.get("C_steps") else None

tnfr/metrics.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+from typing import Dict, Any, List, Tuple
+from collections import defaultdict, Counter
+import statistics
+
+from .constants import DEFAULTS
+from .helpers import _get_attr, clamp01, register_callback
+from .sense import GLYPHS_CANONICAL
+
+# -------------
+# DEFAULTS
+# -------------
+DEFAULTS.setdefault("METRICS", {
+    "enabled": True,
+    "save_by_node": True,     # guarda Tg por nodo (más pesado)
+    "normalize_series": False # glifograma normalizado a fracción por paso
+})
+
+# -------------
+# Utilidades internas
+# -------------
+
+def _ensure_history(G):
+    if "history" not in G.graph:
+        G.graph["history"] = {}
+    return G.graph["history"]
+
+
+def _last_glifo(nd: Dict[str, Any]) -> str | None:
+    hist = nd.get("hist_glifos")
+    if not hist:
+        return None
+    try:
+        return list(hist)[-1]
+    except Exception:
+        return None
+
+
+# -------------
+# Estado nodal para Tg
+# -------------
+
+def _tg_state(nd: Dict[str, Any]) -> Dict[str, Any]:
+    """Estructura interna por nodo para acumular tiempos de corrida por glifo.
+    Campos: curr (glifo actual), run (tiempo acumulado en el glifo actual)
+    """
+    st = nd.setdefault("_Tg", {"curr": None, "run": 0.0})
+    st.setdefault("curr", None)
+    st.setdefault("run", 0.0)
+    return st
+
+
+# -------------
+# Callback principal: actualizar métricas por paso
+# -------------
+
+def _metrics_step(G, *args, **kwargs):
+    """Actualiza métricas operativas TNFR por paso.
+
+    - Tg (tiempo glífico): sumatoria de corridas por glifo (global y por nodo).
+    - Índice de latencia: fracción de nodos en SH’A.
+    - Glifograma: conteo o fracción por glifo en el paso.
+
+    Todos los resultados se guardan en G.graph['history'].
+    """
+    if not G.graph.get("METRICS", DEFAULTS.get("METRICS", {})).get("enabled", True):
+        return
+
+    hist = _ensure_history(G)
+    dt = float(G.graph.get("DT", 1.0))
+    t = float(G.graph.get("_t", 0.0))
+
+    # --- Glifograma (conteos por glifo este paso) ---
+    counts = Counter()
+
+    # --- Índice de latencia: proporción de nodos en SH’A ---
+    n_total = 0
+    n_latent = 0
+
+    # --- Tg: acumular corridas por nodo ---
+    save_by_node = bool(G.graph.get("METRICS", DEFAULTS["METRICS"]).get("save_by_node", True))
+    tg_total = hist.setdefault("Tg_total", defaultdict(float))  # tiempo total por glifo (global)
+    tg_by_node = hist.setdefault("Tg_by_node", {})             # nodo → {glifo: [runs,...]}
+
+    for n in G.nodes():
+        nd = G.nodes[n]
+        g = _last_glifo(nd)
+        if not g:
+            continue
+
+        n_total += 1
+        if g == "SH’A":
+            n_latent += 1
+
+        counts[g] += 1
+
+        st = _tg_state(nd)
+        # Si seguimos en el mismo glifo, acumulamos; si cambiamos, cerramos corrida
+        if st["curr"] is None:
+            st["curr"] = g
+            st["run"] = dt
+        elif g == st["curr"]:
+            st["run"] += dt
+        else:
+            # cerramos corrida anterior
+            prev = st["curr"]
+            dur = float(st["run"])
+            tg_total[prev] += dur
+            if save_by_node:
+                rec = tg_by_node.setdefault(n, defaultdict(list))
+                rec[prev].append(dur)
+            # reiniciamos corrida
+            st["curr"] = g
+            st["run"] = dt
+
+    # Al final del paso, no cerramos la corrida actual: se cerrará cuando cambie.
+
+    # Guardar glifograma (conteos crudos y normalizados)
+    norm = bool(G.graph.get("METRICS", DEFAULTS["METRICS"]).get("normalize_series", False))
+    row = {"t": t}
+    total = max(1, sum(counts.values()))
+    for g in GLYPHS_CANONICAL:
+        c = counts.get(g, 0)
+        row[g] = (c / total) if norm else c
+    hist.setdefault("glifogram", []).append(row)
+
+    # Guardar índice de latencia
+    li = (n_latent / max(1, n_total)) if n_total else 0.0
+    hist.setdefault("latency_index", []).append({"t": t, "value": li})
+
+
+# -------------
+# Registro del callback
+# -------------
+
+def register_metrics_callbacks(G) -> None:
+    register_callback(G, when="after_step", func=_metrics_step, name="metrics_step")
+
+
+# -------------
+# Consultas / reportes
+# -------------
+
+def Tg_global(G, normalize: bool = True) -> Dict[str, float]:
+    """Tiempo glífico total por clase. Si normalize=True, devuelve fracciones del total."""
+    hist = _ensure_history(G)
+    tg_total: Dict[str, float] = hist.get("Tg_total", {})
+    total = sum(tg_total.values()) or 1.0
+    if normalize:
+        return {g: float(tg_total.get(g, 0.0)) / total for g in GLYPHS_CANONICAL}
+    return {g: float(tg_total.get(g, 0.0)) for g in GLYPHS_CANONICAL}
+
+
+def Tg_by_node(G, n, normalize: bool = False) -> Dict[str, float | List[float]]:
+    """Resumen por nodo: si normalize, devuelve medias por glifo; si no, lista de corridas."""
+    hist = _ensure_history(G)
+    rec = hist.get("Tg_by_node", {}).get(n, {})
+    if not normalize:
+        # convertir default dict → list para serializar
+        return {g: list(rec.get(g, [])) for g in GLYPHS_CANONICAL}
+    out = {}
+    for g in GLYPHS_CANONICAL:
+        runs = rec.get(g, [])
+        out[g] = float(statistics.mean(runs)) if runs else 0.0
+        
+    return out
+
+
+def latency_series(G) -> Dict[str, List[float]]:
+    hist = _ensure_history(G)
+    xs = hist.get("latency_index", [])
+    return {
+        "t": [float(x.get("t", i)) for i, x in enumerate(xs)],
+        "value": [float(x.get("value", 0.0)) for x in xs],
+    }
+
+
+def glifogram_series(G) -> Dict[str, List[float]]:
+    hist = _ensure_history(G)
+    xs = hist.get("glifogram", [])
+    if not xs:
+        return {"t": []}
+    out = {"t": [float(x.get("t", i)) for i, x in enumerate(xs)]}
+    for g in GLYPHS_CANONICAL:
+        out[g] = [float(x.get(g, 0.0)) for x in xs]
+    return out
+
+
+def glyph_top(G, k: int = 3) -> List[Tuple[str, float]]:
+    """Top-k glifos por Tg_global (fracción)."""
+    tg = Tg_global(G, normalize=True)
+    return sorted(tg.items(), key=lambda kv: kv[1], reverse=True)[:max(1, int(k))]
+
+
+def glyph_dwell_stats(G, n) -> Dict[str, Dict[str, float]]:
+    """Estadísticos por nodo: mean/median/max de corridas por glifo."""
+    hist = _ensure_history(G)
+    rec = hist.get("Tg_by_node", {}).get(n, {})
+    out = {}
+    for g in GLYPHS_CANONICAL:
+        runs = list(rec.get(g, []))
+        if not runs:
+            out[g] = {"mean": 0.0, "median": 0.0, "max": 0.0, "count": 0}
+        else:
+            out[g] = {
+                "mean": float(statistics.mean(runs)),
+                "median": float(statistics.median(runs)),
+                "max": float(max(runs)),
+                "count": int(len(runs)),
+            }
+    return out

tnfr/operators.py

@@ -154,6 +154,18 @@ _NAME_TO_OP = {
 
 
 def aplicar_glifo(G, n, glifo: str, *, window: Optional[int] = None) -> None:
+    """Aplica un glifo TNFR al nodo `n` con histéresis `window`.
+
+    Los 13 glifos implementan reorganizadores canónicos:
+      A’L (emisión), E’N (recepción), I’L (coherencia), O’Z (disonancia),
+      U’M (acoplamiento), R’A (resonancia), SH’A (silencio), VA’L (expansión),
+      NU’L (contracción), T’HOL (autoorganización), Z’HIR (mutación),
+      NA’V (transición), RE’MESH (recursividad).
+
+    Relación con la gramática: la selección previa debe pasar por
+    `enforce_canonical_grammar` (grammar.py) para respetar compatibilidades,
+    precondición O’Z→Z’HIR y cierres T’HOL[...].
+    """
     glifo = str(glifo)
     op = _NAME_TO_OP.get(glifo)
     if not op:

tnfr/presets.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+from .program import seq, block, wait
+
+
+_PRESETS = {
+    "arranque_resonante": seq("A’L", "E’N", "I’L", "R’A", "VA’L", "U’M", wait(3), "SH’A"),
+    "mutacion_contenida": seq("A’L", "E’N", block("O’Z", "Z’HIR", "I’L", repeat=2), "R’A", "SH’A"),
+    "exploracion_acople": seq(
+        "A’L",
+        "E’N",
+        "I’L",
+        "VA’L",
+        "U’M",
+        block("O’Z", "NA’V", "I’L", repeat=1),
+        "R’A",
+        "SH’A",
+    ),
+}
+
+
+def get_preset(name: str):
+    if name not in _PRESETS:
+        raise KeyError(f"Preset no encontrado: {name}")
+    return _PRESETS[name]

tnfr/program.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+"""program.py — API de secuencias canónicas con T’HOL como primera clase."""
+from typing import Any, Callable, Iterable, List, Optional, Sequence, Tuple, Union
+from dataclasses import dataclass
+from contextlib import contextmanager
+
+from .constants import DEFAULTS
+from .helpers import register_callback
+from .grammar import enforce_canonical_grammar, on_applied_glifo
+from .operators import aplicar_glifo
+from .sense import GLYPHS_CANONICAL
+
+# Tipos básicos
+Glyph = str
+Node = Any
+AdvanceFn = Callable[[Any], None]  # normalmente dynamics.step
+
+# ---------------------
+# Construcciones del DSL
+# ---------------------
+
+@dataclass
+class WAIT:
+    steps: int = 1
+
+@dataclass
+class TARGET:
+    nodes: Optional[Iterable[Node]] = None   # None = todos los nodos
+
+@dataclass
+class THOL:
+    body: Sequence[Any]
+    repeat: int = 1                # cuántas veces repetir el cuerpo
+    force_close: Optional[Glyph] = None  # None → cierre automático (gramática); 'SH’A' o 'NU’L' para forzar
+
+Token = Union[Glyph, WAIT, TARGET, THOL]
+
+# ---------------------
+# Utilidades internas
+# ---------------------
+
+@contextmanager
+def _forced_selector(G, glyph: Glyph):
+    """Sobrescribe temporalmente el selector glífico para forzar `glyph`.
+    Pasa por la gramática canónica antes de aplicar.
+    """
+    prev = G.graph.get("glyph_selector")
+    def selector_forced(_G, _n):
+        return glyph
+    G.graph["glyph_selector"] = selector_forced
+    try:
+        yield
+    finally:
+        if prev is None:
+            G.graph.pop("glyph_selector", None)
+        else:
+            G.graph["glyph_selector"] = prev
+
+def _window(G) -> int:
+    return int(G.graph.get("GLYPH_HYSTERESIS_WINDOW", DEFAULTS.get("GLYPH_HYSTERESIS_WINDOW", 1)))
+
+def _all_nodes(G):
+    return list(G.nodes())
+
+# ---------------------
+# Núcleo de ejecución
+# ---------------------
+
+def _apply_glyph_to_targets(G, g: Glyph, nodes: Optional[Iterable[Node]] = None):
+    nodes = list(nodes) if nodes is not None else _all_nodes(G)
+    w = _window(G)
+    # Pasamos por la gramática antes de aplicar
+    for n in nodes:
+        g_eff = enforce_canonical_grammar(G, n, g)
+        aplicar_glifo(G, n, g_eff, window=w)
+        on_applied_glifo(G, n, g_eff)
+
+def _advance(G, step_fn: Optional[AdvanceFn] = None):
+    if step_fn is None:
+        from .dynamics import step as step_fn
+    step_fn(G)
+
+# ---------------------
+# Compilación de secuencia → lista de operaciones atómicas
+# ---------------------
+
+def _flatten(seq: Sequence[Token], current_target: Optional[TARGET] = None) -> List[Tuple[str, Any]]:
+    """Devuelve lista de operaciones (op, payload).
+    op ∈ { 'GLYPH', 'WAIT', 'TARGET' }.
+    """
+    ops: List[Tuple[str, Any]] = []
+    for item in seq:
+        if isinstance(item, TARGET):
+            ops.append(("TARGET", item))
+        elif isinstance(item, WAIT):
+            ops.append(("WAIT", item.steps))
+        elif isinstance(item, THOL):
+            # abrir bloque T’HOL
+            ops.append(("GLYPH", "T’HOL"))
+            for _ in range(max(1, int(item.repeat))):
+                ops.extend(_flatten(item.body, current_target))
+            # cierre explícito si se pidió; si no, la gramática puede cerrarlo
+            if item.force_close in ("SH’A", "NU’L"):
+                ops.append(("GLYPH", item.force_close))
+        else:
+            # item debería ser un glifo
+            g = str(item)
+            if g not in GLYPHS_CANONICAL:
+                # Permitimos glifos no listados (compat futuros), pero no forzamos
+                pass
+            ops.append(("GLYPH", g))
+    return ops
+
+# ---------------------
+# API pública
+# ---------------------
+
+def play(G, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = None) -> None:
+    """Ejecuta una secuencia canónica sobre el grafo `G`.
+
+    Reglas:
+      - Usa `TARGET(nodes=...)` para cambiar el subconjunto de aplicación.
+      - `WAIT(k)` avanza k pasos con el selector vigente (no fuerza glifo).
+      - `THOL([...], repeat=r, force_close=…)` abre un bloque autoorganizativo,
+        repite el cuerpo y (opcional) fuerza cierre con SH’A/NU’L.
+      - Los glifos se aplican pasando por `enforce_canonical_grammar`.
+    """
+    ops = _flatten(sequence)
+    curr_target: Optional[Iterable[Node]] = None
+
+    # Traza de programa en history
+    if "history" not in G.graph:
+        G.graph["history"] = {}
+    trace = G.graph["history"].setdefault("program_trace", [])
+
+    for op, payload in ops:
+        if op == "TARGET":
+            curr_target = list(payload.nodes) if payload.nodes is not None else None
+            trace.append({"t": float(G.graph.get("_t", 0.0)), "op": "TARGET", "n": len(curr_target or _all_nodes(G))})
+            continue
+        if op == "WAIT":
+            for _ in range(max(1, int(payload))):
+                _advance(G, step_fn)
+            trace.append({"t": float(G.graph.get("_t", 0.0)), "op": "WAIT", "k": int(payload)})
+            continue
+        if op == "GLYPH":
+            g = str(payload)
+            # aplicar + avanzar 1 paso del sistema
+            _apply_glyph_to_targets(G, g, curr_target)
+            _advance(G, step_fn)
+            trace.append({"t": float(G.graph.get("_t", 0.0)), "op": "GLYPH", "g": g})
+            continue
+
+# ---------------------
+# Helpers para construir secuencias de manera cómoda
+# ---------------------
+
+def seq(*tokens: Token) -> List[Token]:
+    return list(tokens)
+
+def block(*tokens: Token, repeat: int = 1, close: Optional[Glyph] = None) -> THOL:
+    return THOL(body=list(tokens), repeat=repeat, force_close=close)
+
+def target(nodes: Optional[Iterable[Node]] = None) -> TARGET:
+    return TARGET(nodes=nodes)
+
+def wait(steps: int = 1) -> WAIT:
+    return WAIT(steps=max(1, int(steps)))

tnfr/scenarios.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+from typing import Any
+import random
+import networkx as nx
+
+from .constants import inject_defaults, DEFAULTS
+
+
+def build_graph(n: int = 24, topology: str = "ring", seed: int | None = 1):
+    rng = random.Random(seed)
+    if topology == "ring":
+        G = nx.cycle_graph(n)
+    elif topology == "complete":
+        G = nx.complete_graph(n)
+    elif topology == "erdos":
+        G = nx.gnp_random_graph(n, 3.0 / n, seed=seed)
+    else:
+        G = nx.path_graph(n)
+
+    for i in G.nodes():
+        nd = G.nodes[i]
+        nd.setdefault("EPI", rng.uniform(0.1, 0.3))
+        nd.setdefault("νf", rng.uniform(0.8, 1.2))
+        nd.setdefault("θ", rng.uniform(-3.1416, 3.1416))
+        nd.setdefault("Si", rng.uniform(0.4, 0.7))
+
+    inject_defaults(G, DEFAULTS)
+    return G