tnfr 3.5.0__tar.gz → 4.0.0__tar.gz

{tnfr-3.5.0/src/tnfr.egg-info → tnfr-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tnfr
-Version: 3.5.0
+Version: 4.0.0
 Summary: TNFR canónica: dinámica glífica modular sobre redes.
 Author: fmg
 License: MIT
@@ -81,6 +81,9 @@ Dynamic: license-file
 
 **Mastering these pieces will let you extend the simulation, build analysis pipelines and connect the theory with computational applications.**
 
+## Optional Node environment
+The repository includes a minimal `package.json` and `netlify.toml` used for an experimental Remix web demo. They are not required for the core Python package; feel free to ignore them unless you plan to build the demo via `npm run build`.
+
 ## Testing
 
 Install the dependencies and project in editable mode before running the test suite with `pytest`:
@@ -89,4 +92,10 @@ Install the dependencies and project in editable mode before running the test su
 pip install networkx
 pip install -e .
 pytest
+
+```
+
+## Installation
+```
+pip install tnfr
 ```

{tnfr-3.5.0 → tnfr-4.0.0}/README.md

@@ -54,6 +54,9 @@
 
 **Mastering these pieces will let you extend the simulation, build analysis pipelines and connect the theory with computational applications.**
 
+## Optional Node environment
+The repository includes a minimal `package.json` and `netlify.toml` used for an experimental Remix web demo. They are not required for the core Python package; feel free to ignore them unless you plan to build the demo via `npm run build`.
+
 ## Testing
 
 Install the dependencies and project in editable mode before running the test suite with `pytest`:
@@ -62,4 +65,10 @@ Install the dependencies and project in editable mode before running the test su
 pip install networkx
 pip install -e .
 pytest
+
+```
+
+## Installation
+```
+pip install tnfr
 ```

{tnfr-3.5.0 → tnfr-4.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tnfr"
-version = "3.5.0"
+version = "4.0.0"
 description = "TNFR canónica: dinámica glífica modular sobre redes."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -28,7 +28,7 @@ classifiers = [
 dependencies = ["networkx>=2.6"]
 
 [project.scripts]
-tnfr = "tnfr.main:main"
+tnfr = "tnfr.cli:main"
 
 [project.urls]
 Homepage = "https://pypi.org/project/tnfr/"

tnfr-4.0.0/src/tnfr/__init__.py

@@ -0,0 +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__ = "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-4.0.0/src/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-3.5.0 → tnfr-4.0.0}/src/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-3.5.0 → tnfr-4.0.0}/src/tnfr/dynamics.py

@@ -18,7 +18,9 @@ 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,
@@ -52,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))
@@ -121,7 +124,23 @@ 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:
@@ -132,16 +151,22 @@ def update_epi_via_nodal_equation(G, *, dt: float = None) -> None:
         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
 
 
 # -------------------------
@@ -432,9 +457,13 @@ def step(G, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool
         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))
         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)

tnfr-4.0.0/src/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