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

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

tnfr/sense.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+from typing import Dict, Any, List, Tuple
+import math
+from collections import Counter
+
+from .constants import DEFAULTS, ALIAS_SI, ALIAS_EPI
+from .helpers import _get_attr, clamp01, register_callback
+
+# -------------------------
+# Canon: orden circular de glifos y ángulos
+# -------------------------
+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)
+})
+
+# -------------------------
+# Utilidades básicas
+# -------------------------
+
+def glyph_angle(g: str) -> float:
+    return float(_SIGMA_ANGLES.get(g, 0.0))
+
+
+def glyph_unit(g: str) -> complex:
+    a = glyph_angle(g)
+    return complex(math.cos(a), math.sin(a))
+
+
+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
+
+
+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
+
+
+# -------------------------
+# σ por nodo y σ global
+# -------------------------
+
+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:
+        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)}
+
+
+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(σ).
+
+    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).
+    """
+    cfg = G.graph.get("SIGMA", DEFAULTS["SIGMA"])
+    weight_mode = weight_mode or cfg.get("weight", "Si")
+    acc = complex(0.0, 0.0)
+    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
+    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)
+    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}
+
+
+# -------------------------
+# Historia / series
+# -------------------------
+
+def _ensure_history(G):
+    if "history" not in G.graph:
+        G.graph["history"] = {}
+    return G.graph["history"]
+
+
+def push_sigma_snapshot(G, t: float | None = None) -> None:
+    cfg = G.graph.get("SIGMA", DEFAULTS["SIGMA"])
+    if not cfg.get("enabled", True):
+        return
+    hist = _ensure_history(G)
+    key = cfg.get("history_key", "sigma_global")
+
+    # Global
+    sv = sigma_vector_global(G, cfg.get("weight", "Si"))
+
+    # Suavizado exponencial (EMA) opcional
+    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)
+    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)
+            if not g:
+                continue
+            a = glyph_angle(g)
+            d = per.setdefault(n, [])
+            d.append({"t": sv["t"], "g": g, "angle": a})
+
+
+# -------------------------
+# Registro como callback automático (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 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", {})
+    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}

tnfr/trace.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+from collections import Counter
+
+from .constants import DEFAULTS
+from .helpers import register_callback
+
+try:
+    from .gamma import kuramoto_R_psi
+except Exception:  # pragma: no cover
+    def kuramoto_R_psi(G):
+        return 0.0, 0.0
+
+try:
+    from .sense import sigma_vector_global
+except Exception:  # pragma: no cover
+    def sigma_vector_global(G, *args, **kwargs):
+        return {"x": 1.0, "y": 0.0, "mag": 1.0, "angle": 0.0, "n": 0}
+
+# -------------------------
+# Defaults
+# -------------------------
+DEFAULTS.setdefault("TRACE", {
+    "enabled": True,
+    "capture": ["gamma", "grammar", "selector", "dnfr_mix", "callbacks", "thol_state", "sigma", "kuramoto", "glifo_counts"],
+    "history_key": "trace_meta",
+})
+
+# -------------------------
+# Helpers
+# -------------------------
+
+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:
+    h = nd.get("hist_glifos")
+    if not h:
+        return None
+    try:
+        return list(h)[-1]
+    except Exception:
+        return None
+
+
+# -------------------------
+# Snapshots
+# -------------------------
+
+def _trace_before(G, *args, **kwargs):
+    if not G.graph.get("TRACE", DEFAULTS["TRACE"]).get("enabled", True):
+        return
+    cfg = G.graph.get("TRACE", DEFAULTS["TRACE"])
+    capture: List[str] = list(cfg.get("capture", []))
+    hist = _ensure_history(G)
+    key = cfg.get("history_key", "trace_meta")
+
+    meta: Dict[str, Any] = {"t": float(G.graph.get("_t", 0.0)), "phase": "before"}
+
+    if "gamma" in capture:
+        meta["gamma"] = dict(G.graph.get("GAMMA", {}))
+
+    if "grammar" in capture:
+        meta["grammar"] = dict(G.graph.get("GRAMMAR_CANON", {}))
+
+    if "selector" in capture:
+        sel = G.graph.get("glyph_selector")
+        meta["selector"] = getattr(sel, "__name__", str(sel)) if sel else None
+
+    if "dnfr_mix" in capture:
+        # tratar de capturar varias convenciones posibles
+        mix = G.graph.get("DNFR_MIX") or G.graph.get("DELTA_NFR_MIX") or G.graph.get("NFR_MIX")
+        meta["dnfr_mix"] = mix if isinstance(mix, dict) else {"value": mix}
+
+    if "callbacks" in capture:
+        # si el motor guarda los callbacks, exponer nombres por fase
+        cb = G.graph.get("_callbacks")
+        if isinstance(cb, dict):
+            out = {k: [getattr(f, "__name__", "fn") for (_, f, *_rest) in v] if isinstance(v, list) else None for k, v in cb.items()}
+            meta["callbacks"] = out
+
+    if "thol_state" in capture:
+        # cuántos nodos tienen bloque T’HOL abierto
+        th_open = 0
+        for n in G.nodes():
+            st = G.nodes[n].get("_GRAM", {})
+            if st.get("thol_open", False):
+                th_open += 1
+        meta["thol_open_nodes"] = th_open
+
+    hist.setdefault(key, []).append(meta)
+
+
+def _trace_after(G, *args, **kwargs):
+    if not G.graph.get("TRACE", DEFAULTS["TRACE"]).get("enabled", True):
+        return
+    cfg = G.graph.get("TRACE", DEFAULTS["TRACE"])
+    capture: List[str] = list(cfg.get("capture", []))
+    hist = _ensure_history(G)
+    key = cfg.get("history_key", "trace_meta")
+
+    meta: Dict[str, Any] = {"t": float(G.graph.get("_t", 0.0)), "phase": "after"}
+
+    if "kuramoto" in capture:
+        R, psi = kuramoto_R_psi(G)
+        meta["kuramoto"] = {"R": float(R), "psi": float(psi)}
+
+    if "sigma" in capture:
+        sv = sigma_vector_global(G)
+        meta["sigma"] = {"x": float(sv.get("x", 1.0)), "y": float(sv.get("y", 0.0)), "mag": float(sv.get("mag", 1.0)), "angle": float(sv.get("angle", 0.0))}
+
+    if "glifo_counts" in capture:
+        cnt = Counter()
+        for n in G.nodes():
+            g = _last_glifo(G.nodes[n])
+            if g:
+                cnt[g] += 1
+        meta["glifos"] = dict(cnt)
+
+    hist.setdefault(key, []).append(meta)
+
+
+# -------------------------
+# API
+# -------------------------
+
+def register_trace(G) -> None:
+    """Activa snapshots before/after step y vuelca metadatos operativos en history.
+
+    Guarda en G.graph['history'][TRACE.history_key] una lista de entradas {'phase': 'before'|'after', ...} con:
+      - gamma: especificación activa de Γi(R)
+      - grammar: configuración de gramática canónica
+      - selector: nombre del selector glífico
+      - dnfr_mix: mezcla (si el motor la expone en G.graph)
+      - callbacks: callbacks registrados por fase (si están en G.graph['_callbacks'])
+      - thol_open_nodes: cuántos nodos tienen bloque T’HOL abierto
+      - kuramoto: (R, ψ) de la red
+      - sigma: vector global del plano del sentido
+      - glifos: conteos por glifo tras el paso
+    """
+    register_callback(G, when="before_step", func=_trace_before, name="trace_before")
+    register_callback(G, when="after_step", func=_trace_after, name="trace_after")

tnfr/types.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Dict, Any
+
+
+@dataclass
+class NodeState:
+    EPI: float = 0.0
+    vf: float = 1.0   # νf
+    theta: float = 0.0  # θ
+    Si: float = 0.5
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    def to_attrs(self) -> Dict[str, Any]:
+        d = {"EPI": self.EPI, "νf": self.vf, "θ": self.theta, "Si": self.Si}
+        d.update(self.extra)
+        return d