tnfr 3.0.3__tar.gz → 4.0.0__tar.gz

tnfr-3.0.3/LICENSE.txt → tnfr-4.0.0/LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2025 TNFR - Teoría de la naturaleza fractral resonante
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

tnfr-4.0.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: tnfr
+Version: 4.0.0
+Summary: TNFR canónica: dinámica glífica modular sobre redes.
+Author: fmg
+License: MIT
+Project-URL: Homepage, https://pypi.org/project/tnfr/
+Project-URL: Repository, https://github.com/fermga/Teoria-de-la-naturaleza-fractal-resonante-TNFR-
+Keywords: TNFR,fractal resonante,resonancia,glifos,networkx,dinámica,coherencia,EPI,Kuramoto
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: networkx>=2.6
+Dynamic: license-file
+
+# General Project Structure
+
+* **Package entry point.** `__init__.py` registers modules under short names to avoid circular imports and exposes the public API: `preparar_red`, `step`, `run`, and observation utilities.
+
+* **Configuration & constants.** `constants.py` centralizes default parameters (discretization, EPI and νf ranges, mixing weights, re-mesh limits, etc.) and provides utilities to inject them into the network (`attach_defaults`, `merge_overrides`), along with standardized aliases for node attributes.
+
+* **Cross-cutting utilities.** `helpers.py` offers core numeric helpers, alias-based attribute accessors, neighborhood statistics, glyph history, a callback system, and computation of the sense index `Si` for each node.
+
+* **Dynamics engine.** `dynamics.py` implements the simulation loop: ΔNFR field computation, nodal equation integration, glyph selection/application, clamps, phase coordination, history updates, and conditional re-mesh (`step` and `run`).
+
+* **Glyph operators.** `operators.py` defines the 13 glyphs as local transformations, a dispatcher `aplicar_glifo`, and both direct and stability-conditioned re-mesh utilities.
+
+* **Observers & metrics.** `observers.py` registers standard callbacks and computes global coherence, phase synchrony, Kuramoto order, glyph distribution, and the sense vector `Σ⃗`, among others.
+
+* **Simulation orchestration.** `ontosim.py` prepares a NetworkX graph, attaches configuration, and initializes attributes (EPI, phases, frequencies) before delegating dynamics to `dynamics.step`/`run`.
+
+* **Demo CLI.** `main.py` generates an Erdős–Rényi network, lets you tweak basic parameters, and runs the simulation while displaying final metrics.
+
+---
+
+## Key Concepts to Grasp
+
+* **Aliased dependency tree.** Modules import each other via global aliases to simplify access and prevent cycles—essential for navigating the code unambiguously.
+
+* **Normalized node attributes.** All data (EPI, phase `θ`, frequency `νf`, `ΔNFR`, etc.) live in `G.nodes[n]` under compatible alias names, making extensions and custom hooks straightforward.
+
+* **Sense Index (`Si`).** Combines normalized frequency, phase dispersion, and field magnitude to evaluate each node’s “sense,” influencing glyph selection.
+
+* **Step-wise engine.** `dynamics.step` orchestrates eight phases: field computation, `Si`, glyph selection & application, integration, clamps, phase coordination, history update, and conditioned re-mesh.
+
+* **Glyphs as operators.** Each glyph applies a smooth transformation to node attributes (emission, diffusion, coupling, dissonance, etc.), dispatched by a configurable, typographic name.
+
+* **Network re-mesh.** Mixes the current state with a past one (memory `τ`) to stabilize the network, with clear precedence for `α` and conditions based on recent stability and synchrony history.
+
+* **Callbacks & observers.** The `Γ(R)` system lets you hook functions before/after each step and after re-mesh, enabling monitoring or external intervention.
+
+---
+
+## Recommendations for Going Deeper
+
+* **NetworkX & the Graph API.** Get comfortable with how NetworkX handles attributes and topology; all dynamics operate on `Graph` objects and their properties.
+
+* **Extending the ΔNFR field.** Explore `set_delta_nfr_hook` to implement alternative nodal fields and learn how metadata and mixing weights are recorded.
+
+* **Designing new glyphs.** Review `operators.py` to add operators or adjust factors in `DEFAULTS['GLYPH_FACTORS']`.
+
+* **Custom observers.** Implement your own metrics via `register_callback` or by extending `observers.py` to measure phenomena specific to your study.
+
+* **Theoretical reading.** For conceptual background, see the included PDFs (`TNFR.pdf`, *El Pulso que nos Atraviesa*), which deepen the fractal-resonant framework.
+
+* **Advanced parameters.** Experiment with adaptive phase coordination, stability criteria, and the glyph grammar to observe their impact on network self-organization.
+
+---
+
+**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`:
+
+```
+pip install networkx
+pip install -e .
+pytest
+
+```
+
+## Installation
+```
+pip install tnfr
+```

tnfr-4.0.0/README.md

@@ -0,0 +1,74 @@
+# General Project Structure
+
+* **Package entry point.** `__init__.py` registers modules under short names to avoid circular imports and exposes the public API: `preparar_red`, `step`, `run`, and observation utilities.
+
+* **Configuration & constants.** `constants.py` centralizes default parameters (discretization, EPI and νf ranges, mixing weights, re-mesh limits, etc.) and provides utilities to inject them into the network (`attach_defaults`, `merge_overrides`), along with standardized aliases for node attributes.
+
+* **Cross-cutting utilities.** `helpers.py` offers core numeric helpers, alias-based attribute accessors, neighborhood statistics, glyph history, a callback system, and computation of the sense index `Si` for each node.
+
+* **Dynamics engine.** `dynamics.py` implements the simulation loop: ΔNFR field computation, nodal equation integration, glyph selection/application, clamps, phase coordination, history updates, and conditional re-mesh (`step` and `run`).
+
+* **Glyph operators.** `operators.py` defines the 13 glyphs as local transformations, a dispatcher `aplicar_glifo`, and both direct and stability-conditioned re-mesh utilities.
+
+* **Observers & metrics.** `observers.py` registers standard callbacks and computes global coherence, phase synchrony, Kuramoto order, glyph distribution, and the sense vector `Σ⃗`, among others.
+
+* **Simulation orchestration.** `ontosim.py` prepares a NetworkX graph, attaches configuration, and initializes attributes (EPI, phases, frequencies) before delegating dynamics to `dynamics.step`/`run`.
+
+* **Demo CLI.** `main.py` generates an Erdős–Rényi network, lets you tweak basic parameters, and runs the simulation while displaying final metrics.
+
+---
+
+## Key Concepts to Grasp
+
+* **Aliased dependency tree.** Modules import each other via global aliases to simplify access and prevent cycles—essential for navigating the code unambiguously.
+
+* **Normalized node attributes.** All data (EPI, phase `θ`, frequency `νf`, `ΔNFR`, etc.) live in `G.nodes[n]` under compatible alias names, making extensions and custom hooks straightforward.
+
+* **Sense Index (`Si`).** Combines normalized frequency, phase dispersion, and field magnitude to evaluate each node’s “sense,” influencing glyph selection.
+
+* **Step-wise engine.** `dynamics.step` orchestrates eight phases: field computation, `Si`, glyph selection & application, integration, clamps, phase coordination, history update, and conditioned re-mesh.
+
+* **Glyphs as operators.** Each glyph applies a smooth transformation to node attributes (emission, diffusion, coupling, dissonance, etc.), dispatched by a configurable, typographic name.
+
+* **Network re-mesh.** Mixes the current state with a past one (memory `τ`) to stabilize the network, with clear precedence for `α` and conditions based on recent stability and synchrony history.
+
+* **Callbacks & observers.** The `Γ(R)` system lets you hook functions before/after each step and after re-mesh, enabling monitoring or external intervention.
+
+---
+
+## Recommendations for Going Deeper
+
+* **NetworkX & the Graph API.** Get comfortable with how NetworkX handles attributes and topology; all dynamics operate on `Graph` objects and their properties.
+
+* **Extending the ΔNFR field.** Explore `set_delta_nfr_hook` to implement alternative nodal fields and learn how metadata and mixing weights are recorded.
+
+* **Designing new glyphs.** Review `operators.py` to add operators or adjust factors in `DEFAULTS['GLYPH_FACTORS']`.
+
+* **Custom observers.** Implement your own metrics via `register_callback` or by extending `observers.py` to measure phenomena specific to your study.
+
+* **Theoretical reading.** For conceptual background, see the included PDFs (`TNFR.pdf`, *El Pulso que nos Atraviesa*), which deepen the fractal-resonant framework.
+
+* **Advanced parameters.** Experiment with adaptive phase coordination, stability criteria, and the glyph grammar to observe their impact on network self-organization.
+
+---
+
+**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`:
+
+```
+pip install networkx
+pip install -e .
+pytest
+
+```
+
+## Installation
+```
+pip install tnfr
+```

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

@@ -1,11 +1,11 @@
 [project]
 name = "tnfr"
-version = "3.0.3"
+version = "4.0.0"
 description = "TNFR canónica: dinámica glífica modular sobre redes."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
-authors = [{ name = "Fer" }]
+authors = [{ name = "fmg" }]
 keywords = [
   "TNFR", "fractal resonante", "resonancia", "glifos",
   "networkx", "dinámica", "coherencia", "EPI", "Kuramoto"
@@ -24,8 +24,16 @@ classifiers = [
   "Topic :: Scientific/Engineering :: Artificial Intelligence",
   "Topic :: Scientific/Engineering :: Information Analysis"
 ]
+
 dependencies = ["networkx>=2.6"]
 
+[project.scripts]
+tnfr = "tnfr.cli:main"
+
 [project.urls]
 Homepage = "https://pypi.org/project/tnfr/"
 Repository = "https://github.com/fermga/Teoria-de-la-naturaleza-fractal-resonante-TNFR-"
+
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"

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.0.3 → 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: