tnfr 4.5.0__py3-none-any.whl → 4.5.2__py3-none-any.whl

tnfr/observers.py

@@ -1,161 +1,159 @@
-"""
-observers.py — TNFR canónica
+"""Observer management."""
 
-Observadores y métricas auxiliares.
-"""
 from __future__ import annotations
-from collections import Counter
-from typing import Dict, Any
-import math
+from functools import partial
+import statistics
+from statistics import StatisticsError, pvariance
+
+from .constants import get_aliases
+from .alias import get_attr
+from .helpers.numeric import angle_diff
+from .callback_utils import CallbackEvent, callback_manager
+from .glyph_history import (
+    ensure_history,
+    count_glyphs,
+    append_metric,
+)
+from .collections_utils import normalize_counter, mix_groups
+from .constants_glyphs import GLYPH_GROUPS
+from .gamma import kuramoto_R_psi
+from .logging_utils import get_logger
+from .import_utils import get_numpy
+from .metrics.common import compute_coherence
+from .validators import validate_window
+
+ALIAS_THETA = get_aliases("THETA")
+
+__all__ = (
+    "attach_standard_observer",
+    "kuramoto_metrics",
+    "phase_sync",
+    "kuramoto_order",
+    "glyph_load",
+    "wbar",
+    "DEFAULT_GLYPH_LOAD_SPAN",
+    "DEFAULT_WBAR_SPAN",
+)
+
+
+logger = get_logger(__name__)
+
+DEFAULT_GLYPH_LOAD_SPAN = 50
+DEFAULT_WBAR_SPAN = 25
+
 
-from .constants import ALIAS_DNFR, ALIAS_EPI, ALIAS_THETA, ALIAS_dEPI
-from .helpers import _get_attr, list_mean, register_callback
 
 # -------------------------
 # Observador estándar Γ(R)
 # -------------------------
-def _std_log(G, kind: str, ctx: dict):
-    """Guarda eventos compactos en history['events']."""
-    h = G.graph.setdefault("history", {})
-    h.setdefault("events", []).append((kind, dict(ctx)))
+def _std_log(kind: str, G, ctx: dict):
+    """Store compact events in ``history['events']``."""
+    h = ensure_history(G)
+    append_metric(h, "events", (kind, dict(ctx)))
 
-def std_before(G, ctx):
-    _std_log(G, "before", ctx)
 
-def std_after(G, ctx):
-    _std_log(G, "after", ctx)
+_STD_CALLBACKS = {
+    CallbackEvent.BEFORE_STEP.value: partial(_std_log, "before"),
+    CallbackEvent.AFTER_STEP.value: partial(_std_log, "after"),
+    CallbackEvent.ON_REMESH.value: partial(_std_log, "remesh"),
+}
 
-def std_on_remesh(G, ctx):
-    _std_log(G, "remesh", ctx)
 
 def attach_standard_observer(G):
-    """Registra callbacks estándar: before_step, after_step, on_remesh."""
-    register_callback(G, "before_step", std_before)
-    register_callback(G, "after_step",  std_after)
-    register_callback(G, "on_remesh",   std_on_remesh)
-    G.graph.setdefault("_STD_OBSERVER", "attached")
+    """Register standard callbacks: before_step, after_step, on_remesh."""
+    if G.graph.get("_STD_OBSERVER"):
+        return G
+    for event, fn in _STD_CALLBACKS.items():
+        callback_manager.register_callback(G, event, fn)
+    G.graph["_STD_OBSERVER"] = "attached"
     return G
 
-def coherencia_global(G) -> float:
-    """Proxy de C(t): alta cuando |ΔNFR| y |dEPI_dt| son pequeños."""
-    dnfr = list_mean(abs(_get_attr(G.nodes[n], ALIAS_DNFR, 0.0)) for n in G.nodes())
-    dEPI = list_mean(abs(_get_attr(G.nodes[n], ALIAS_dEPI, 0.0)) for n in G.nodes())
-    return 1.0 / (1.0 + dnfr + dEPI)
+
+def _ensure_nodes(G) -> bool:
+    """Return ``True`` when the graph has nodes."""
+    return bool(G.number_of_nodes())
+
+
+def kuramoto_metrics(G) -> tuple[float, float]:
+    """Return Kuramoto order ``R`` and mean phase ``ψ``.
+
+    Delegates to :func:`kuramoto_R_psi` and performs the computation exactly
+    once per invocation.
+    """
+    return kuramoto_R_psi(G)
 
 
-def sincronía_fase(G) -> float:
-    X = [math.cos(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
-    Y = [math.sin(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
-    if not X:
+def phase_sync(G, R: float | None = None, psi: float | None = None) -> float:
+    if not _ensure_nodes(G):
         return 1.0
-    th = math.atan2(sum(Y) / len(Y), sum(X) / len(X))
-    # varianza angular aproximada (0 = muy sincronizado)
-    import statistics as st
-    var = (
-        st.pvariance(
-            [
-                (
-                    (_get_attr(G.nodes[n], ALIAS_THETA, 0.0) - th + math.pi)
-                    % (2 * math.pi)
-                    - math.pi
-                )
-                for n in G.nodes()
-            ]
-        )
-        if len(X) > 1
-        else 0.0
+    if R is None or psi is None:
+        R_calc, psi_calc = kuramoto_metrics(G)
+        if R is None:
+            R = R_calc
+        if psi is None:
+            psi = psi_calc
+    diffs = (
+        angle_diff(get_attr(data, ALIAS_THETA, 0.0), psi)
+        for _, data in G.nodes(data=True)
     )
+    # Try NumPy for a vectorised population variance
+    np = get_numpy()
+    if np is not None:
+        arr = np.fromiter(diffs, dtype=float)
+        var = float(np.var(arr)) if arr.size else 0.0
+    else:
+        try:
+            var = pvariance(diffs)
+        except StatisticsError:
+            var = 0.0
     return 1.0 / (1.0 + var)
 
-def orden_kuramoto(G) -> float:
-    """R en [0,1], 1 = fases perfectamente alineadas."""
-    X = [math.cos(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
-    Y = [math.sin(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
-    if not X:
+
+def kuramoto_order(
+    G, R: float | None = None, psi: float | None = None
+) -> float:
+    """R in [0,1], 1 means perfectly aligned phases."""
+    if not _ensure_nodes(G):
         return 1.0
-    R = ((sum(X)**2 + sum(Y)**2) ** 0.5) / max(1, len(X))
+    if R is None or psi is None:
+        R, psi = kuramoto_metrics(G)
     return float(R)
 
-def carga_glifica(G, window: int | None = None) -> dict:
-    """Devuelve distribución de glifos aplicados en la red.
-    - window: si se indica, cuenta solo los últimos `window` eventos por nodo; si no, usa el maxlen del deque.
-    Retorna un dict con proporciones por glifo y agregados útiles.
+
+def glyph_load(G, window: int | None = None) -> dict:
+    """Return distribution of glyphs applied in the network.
+
+    - ``window``: if provided, count only the last ``window`` events per node;
+      otherwise use :data:`DEFAULT_GLYPH_LOAD_SPAN`.
+    Returns a dict with proportions per glyph and useful aggregates.
     """
-    total = Counter()
-    for n in G.nodes():
-        nd = G.nodes[n]
-        hist = nd.get("hist_glifos")
-        if not hist:
-            continue
-        seq = list(hist)
-        if window is not None and window > 0:
-            seq = seq[-window:]
-        total.update(seq)
-
-
-    count = sum(total.values())
+    if window == 0:
+        return {"_count": 0}
+    if window is None:
+        window_int = DEFAULT_GLYPH_LOAD_SPAN
+    else:
+        window_int = validate_window(window, positive=True)
+    total = count_glyphs(G, window=window_int, last_only=(window_int == 1))
+    dist, count = normalize_counter(total)
     if count == 0:
         return {"_count": 0}
-
-
-    # Proporciones por glifo
-    dist = {k: v / count for k, v in total.items()}
-
-
-    # Agregados conceptuales (puedes ajustar categorías)
-    estabilizadores = ["I’L", "R’A", "U’M", "SH’A"]
-    disruptivos = ["O’Z", "Z’HIR", "NA’V", "T’HOL"]
-
-
-    dist["_estabilizadores"] = sum(dist.get(k, 0.0) for k in estabilizadores)
-    dist["_disruptivos"] = sum(dist.get(k, 0.0) for k in disruptivos)
+    dist = mix_groups(dist, GLYPH_GROUPS)
     dist["_count"] = count
     return dist
 
-def sigma_vector(G, window: int | None = None) -> dict:
-    """Vector de sentido Σ⃗ a partir de la distribución glífica reciente.
-    Devuelve dict con x, y, mag (0..1) y angle (rad)."""
-    # Distribución glífica (proporciones)
-    dist = carga_glifica(G, window=window)
-    if not dist or dist.get("_count", 0) == 0:
-        return {"x": 0.0, "y": 0.0, "mag": 0.0, "angle": 0.0}
-
-    # Mapeo polar de glifos principales en el plano de sentido
-    # (ordenado estabilización→expansión→acoplamiento→silencio→disonancia→mutación→transición→autoorg.)
-    angles = {
-        "I’L": 0.0,
-        "R’A": math.pi/4,
-        "U’M": math.pi/2,
-        "SH’A": 3*math.pi/4,
-        "O’Z": math.pi,
-        "Z’HIR": 5*math.pi/4,
-        "NA’V": 3*math.pi/2,
-        "T’HOL": 7*math.pi/4,
-    }
-    # Normaliza solo sobre glifos mapeados
-    total = sum(dist.get(k, 0.0) for k in angles.keys())
-    if total <= 0:
-        return {"x": 0.0, "y": 0.0, "mag": 0.0, "angle": 0.0}
-
-    x = 0.0
-    y = 0.0
-    for k, a in angles.items():
-        p = dist.get(k, 0.0) / total
-        x += p * math.cos(a)
-        y += p * math.sin(a)
-
-    mag = (x*x + y*y) ** 0.5
-    ang = math.atan2(y, x)
-    return {"x": float(x), "y": float(y), "mag": float(mag), "angle": float(ang)}
 
 def wbar(G, window: int | None = None) -> float:
-    """Devuelve W̄ = media de C(t) en una ventana reciente."""
-    hist = G.graph.get("history", {})
-    cs = hist.get("C_steps", [])
+    """Return W̄ = mean of ``C(t)`` over a recent window.
+
+    Uses :func:`ensure_history` to obtain ``G.graph['history']`` and falls back
+    to the instantaneous coherence when ``"C_steps"`` is missing or empty.
+    """
+    hist = ensure_history(G)
+    cs = list(hist.get("C_steps", []))
     if not cs:
         # fallback: coherencia instantánea
-        return coherencia_global(G)
-    if window is None:
-        window = int(G.graph.get("WBAR_WINDOW", 25))
-    w = min(len(cs), max(1, int(window)))
-    return float(sum(cs[-w:]) / w)
+        return compute_coherence(G)
+    w_param = DEFAULT_WBAR_SPAN if window is None else window
+    w = validate_window(w_param, positive=True)
+    w = min(len(cs), w)
+    return float(statistics.fmean(cs[-w:]))

tnfr/ontosim.py

@@ -1,140 +1,140 @@
-"""
-ontosim.py — TNFR canónica
-
-Módulo de orquestación mínima que encadena:
-ΔNFR (campo) → Si → glifos → ecuación nodal → clamps → U’M → observadores → RE’MESH
-"""
-from __future__ import annotations
-import networkx as nx
-import math
-import random
+"""Orchestrate the canonical simulation."""
+
+from __future__ import annotations
 from collections import deque
-
-from .constants import DEFAULTS, attach_defaults
+from typing import TYPE_CHECKING
+
+from .callback_utils import CallbackEvent
+from .constants import METRIC_DEFAULTS, inject_defaults, get_param
 from .dynamics import step as _step, run as _run
 from .dynamics import default_compute_delta_nfr
-
-# API de alto nivel
-
-def preparar_red(G: nx.Graph, *, override_defaults: bool = False, **overrides) -> nx.Graph:
-    attach_defaults(G, override=override_defaults)
-    if overrides:
+from .initialization import init_node_attrs
+from .glyph_history import append_metric
+from .import_utils import cached_import
+
+if TYPE_CHECKING:  # pragma: no cover
+    import networkx as nx  # type: ignore[import-untyped]
+
+# API de alto nivel
+__all__ = ("preparar_red", "step", "run")
+
+
+def preparar_red(
+    G: "nx.Graph",
+    *,
+    init_attrs: bool = True,
+    override_defaults: bool = False,
+    **overrides,
+) -> "nx.Graph":
+    """Prepare ``G`` for simulation.
+
+    Parameters
+    ----------
+    init_attrs:
+        Run ``init_node_attrs`` when ``True`` (default), leaving node
+        attributes untouched when ``False``.
+    override_defaults:
+        If ``True``, :func:`inject_defaults` overwrites existing entries.
+    **overrides:
+        Parameters applied after the defaults phase.
+    """
+    inject_defaults(G, override=override_defaults)
+    if overrides:
         from .constants import merge_overrides
-        merge_overrides(G, **overrides)
-    # Inicializaciones blandas
-    G.graph.setdefault("history", {
-        "C_steps": [],
-        "stable_frac": [],
-        "phase_sync": [],
-        "kuramoto_R": [], 
-        "sense_sigma_x": [],
-        "sense_sigma_y": [],
-        "sense_sigma_mag": [],
-        "sense_sigma_angle": [],
-        "iota": [],
-        "glyph_load_estab": [],
-        "glyph_load_disr": [],
-        "Si_mean": [],
-        "Si_hi_frac": [],
-        "Si_lo_frac": [],
-        "W_bar": [],
-        "phase_kG": [],
-        "phase_kL": [], 
-        "phase_state": [],
-        "phase_R": [], 
-        "phase_disr": [],
-    })
-    tau = int(G.graph.get("REMESH_TAU", DEFAULTS["REMESH_TAU"]))
+
+        merge_overrides(G, **overrides)
+    # Inicializaciones blandas
+    ph_len = int(
+        G.graph.get(
+            "PHASE_HISTORY_MAXLEN", METRIC_DEFAULTS["PHASE_HISTORY_MAXLEN"]
+        )
+    )
+    hist_keys = [
+        "C_steps",
+        "stable_frac",
+        "phase_sync",
+        "kuramoto_R",
+        "sense_sigma_x",
+        "sense_sigma_y",
+        "sense_sigma_mag",
+        "sense_sigma_angle",
+        "iota",
+        "glyph_load_estab",
+        "glyph_load_disr",
+        "Si_mean",
+        "Si_hi_frac",
+        "Si_lo_frac",
+        "W_bar",
+        "phase_kG",
+        "phase_kL",
+    ]
+    history = {k: [] for k in hist_keys}
+    history.update(
+        {
+            "phase_state": deque(maxlen=ph_len),
+            "phase_R": deque(maxlen=ph_len),
+            "phase_disr": deque(maxlen=ph_len),
+        }
+    )
+    G.graph.setdefault("history", history)
+    # Memoria global de REMESH
+    tau = int(get_param(G, "REMESH_TAU_GLOBAL"))
     maxlen = max(2 * tau + 5, 64)
     G.graph.setdefault("_epi_hist", deque(maxlen=maxlen))
-    # Auto-attach del observador estándar si se pide
-    if G.graph.get("ATTACH_STD_OBSERVER", False):
-        try:
-            from .observers import attach_standard_observer
-            attach_standard_observer(G)
-        except Exception as e:
-            G.graph.setdefault("_callback_errors", []).append(
-                {"event":"attach_std_observer","error":repr(e)}
-            )
-    # Hook explícito para ΔNFR (se puede sustituir luego con dynamics.set_delta_nfr_hook)
-    G.graph.setdefault("compute_delta_nfr", default_compute_delta_nfr)
-    G.graph.setdefault("_dnfr_hook_name", "default_compute_delta_nfr")
-    # Callbacks Γ(R): before_step / after_step / on_remesh
-    G.graph.setdefault("callbacks", {
-        "before_step": [],
-        "after_step": [],
-        "on_remesh": [],
-    })
-    G.graph.setdefault("_CALLBACKS_DOC",
-        "Interfaz Γ(R): registrar funciones (G, ctx) en callbacks['before_step'|'after_step'|'on_remesh']")
-    
-    # --- Inicialización configurable de θ y νf ---
-    seed = int(G.graph.get("RANDOM_SEED", 0))
-    init_rand_phase = bool(G.graph.get("INIT_RANDOM_PHASE", DEFAULTS.get("INIT_RANDOM_PHASE", True)))
-
-    th_min = float(G.graph.get("INIT_THETA_MIN",  DEFAULTS.get("INIT_THETA_MIN", -math.pi)))
-    th_max = float(G.graph.get("INIT_THETA_MAX",  DEFAULTS.get("INIT_THETA_MAX",  math.pi)))
-
-    vf_mode = str(G.graph.get("INIT_VF_MODE", DEFAULTS.get("INIT_VF_MODE", "uniform"))).lower()
-    vf_min_lim = float(G.graph.get("VF_MIN", DEFAULTS["VF_MIN"]))
-    vf_max_lim = float(G.graph.get("VF_MAX", DEFAULTS["VF_MAX"]))
-
-    vf_uniform_min = G.graph.get("INIT_VF_MIN", DEFAULTS.get("INIT_VF_MIN", None))
-    vf_uniform_max = G.graph.get("INIT_VF_MAX", DEFAULTS.get("INIT_VF_MAX", None))
-    if vf_uniform_min is None: vf_uniform_min = vf_min_lim
-    if vf_uniform_max is None: vf_uniform_max = vf_max_lim
-
-    vf_mean = float(G.graph.get("INIT_VF_MEAN", DEFAULTS.get("INIT_VF_MEAN", 0.5)))
-    vf_std  = float(G.graph.get("INIT_VF_STD",  DEFAULTS.get("INIT_VF_STD",  0.15)))
-    clamp_to_limits = bool(G.graph.get("INIT_VF_CLAMP_TO_LIMITS", DEFAULTS.get("INIT_VF_CLAMP_TO_LIMITS", True)))
-
-    for idx, n in enumerate(G.nodes()):
-        nd = G.nodes[n]
-        # EPI canónico
-        nd.setdefault("EPI", 0.0)
-
-        # θ aleatoria (opt-in por flag)
-        if init_rand_phase:
-            th_rng = random.Random(seed + 1009 * idx)
-            nd["θ"] = th_rng.uniform(th_min, th_max)
-        else:
-            nd.setdefault("θ", 0.0)
-
-        # νf distribuida
-        if vf_mode == "uniform":
-            vf_rng = random.Random(seed * 1000003 + idx)
-            vf = vf_rng.uniform(float(vf_uniform_min), float(vf_uniform_max))
-        elif vf_mode == "normal":
-            vf_rng = random.Random(seed * 1000003 + idx)
-            # normal truncada simple (rechazo)
-            for _ in range(16):
-                cand = vf_rng.normalvariate(vf_mean, vf_std)
-                if vf_min_lim <= cand <= vf_max_lim:
-                    vf = cand
-                    break
-            else:
-                # fallback: clamp del último candidato
-                vf = min(max(vf_rng.normalvariate(vf_mean, vf_std), vf_min_lim), vf_max_lim)
-        else:
-            # fallback: conserva si existe, si no 0.5
-            vf = float(nd.get("νf", 0.5))
-
-        if clamp_to_limits:
-            vf = min(max(vf, vf_min_lim), vf_max_lim)
-
-        nd["νf"] = float(vf)
-        
-    return G
-
-def step(G: nx.Graph, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool = True) -> None:
-    _step(G, dt=dt, use_Si=use_Si, apply_glyphs=apply_glyphs)
-
-def run(G: nx.Graph, steps: int, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool = True) -> None:
-    _run(G, steps=steps, dt=dt, use_Si=use_Si, apply_glyphs=apply_glyphs)
-
-# Helper rápido para pruebas manuales
-if __name__ == "__main__":
-    G = nx.erdos_renyi_graph(30, 0.15)
-    preparar_red(G)
-    run(G, 100)
-    print("C(t) muestras:", G.graph["history"]["C_steps"][-5:])
+    # Auto-attach del observador estándar si se pide
+    if G.graph.get("ATTACH_STD_OBSERVER", False):
+        attach_standard_observer = cached_import(
+            "tnfr.observers",
+            "attach_standard_observer",
+        )
+        if attach_standard_observer is not None:
+            attach_standard_observer(G)
+        else:
+            append_metric(
+                G.graph,
+                "_callback_errors",
+                {"event": "attach_std_observer", "error": "ImportError"},
+            )
+    # Hook explícito para ΔNFR (se puede sustituir luego con
+    # dynamics.set_delta_nfr_hook)
+    G.graph.setdefault("compute_delta_nfr", default_compute_delta_nfr)
+    G.graph.setdefault("_dnfr_hook_name", "default_compute_delta_nfr")
+    # Callbacks Γ(R): before_step / after_step / on_remesh
+    G.graph.setdefault(
+        "callbacks",
+        {
+            CallbackEvent.BEFORE_STEP.value: [],
+            CallbackEvent.AFTER_STEP.value: [],
+            CallbackEvent.ON_REMESH.value: [],
+        },
+    )
+    G.graph.setdefault(
+        "_CALLBACKS_DOC",
+        "Interfaz Γ(R): registrar pares (name, func) con firma (G, ctx) "
+        "en callbacks['before_step'|'after_step'|'on_remesh']",
+    )
+
+    if init_attrs:
+        init_node_attrs(G, override=True)
+    return G
+
+
+def step(
+    G: "nx.Graph",
+    *,
+    dt: float | None = None,
+    use_Si: bool = True,
+    apply_glyphs: bool = True,
+) -> None:
+    _step(G, dt=dt, use_Si=use_Si, apply_glyphs=apply_glyphs)
+
+
+def run(
+    G: "nx.Graph",
+    steps: int,
+    *,
+    dt: float | None = None,
+    use_Si: bool = True,
+    apply_glyphs: bool = True,
+) -> None:
+    _run(G, steps=steps, dt=dt, use_Si=use_Si, apply_glyphs=apply_glyphs)