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

tnfr/node.pyi

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import numpy as np
+from .mathematics import (
+    CoherenceOperator,
+    FrequencyOperator,
+    HilbertSpace,
+    NFRValidator,
+    StateProjector,
+)
+from .types import (
+    CouplingWeight,
+    DeltaNFR,
+    EPIValue,
+    NodeId,
+    Phase,
+    SecondDerivativeEPI,
+    SenseIndex,
+    StructuralFrequency,
+    TNFRGraph,
+)
+from collections.abc import Hashable
+from dataclasses import dataclass
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    MutableMapping,
+    Protocol,
+    Sequence,
+    SupportsFloat,
+    TypeVar,
+)
+
+__all__ = ["NodeNX", "NodeProtocol", "add_edge"]
+
+T = TypeVar("T")
+
+@dataclass(frozen=True)
+class AttrSpec:
+    aliases: tuple[str, ...]
+    default: Any = ...
+    getter: Callable[[MutableMapping[str, Any], tuple[str, ...], Any], Any] = ...
+    setter: Callable[..., None] = ...
+    to_python: Callable[[Any], Any] = ...
+    to_storage: Callable[[Any], Any] = ...
+    use_graph_setter: bool = ...
+    def build_property(self) -> property: ...
+
+def add_edge(
+    graph: TNFRGraph,
+    n1: NodeId,
+    n2: NodeId,
+    weight: CouplingWeight | SupportsFloat | str,
+    overwrite: bool = False,
+) -> None: ...
+
+class NodeProtocol(Protocol):
+    EPI: EPIValue
+    vf: StructuralFrequency
+    theta: Phase
+    Si: SenseIndex
+    epi_kind: str
+    dnfr: DeltaNFR
+    d2EPI: SecondDerivativeEPI
+    graph: MutableMapping[str, Any]
+    def neighbors(self) -> Iterable[NodeProtocol | Hashable]: ...
+    def has_edge(self, other: NodeProtocol) -> bool: ...
+    def add_edge(
+        self, other: NodeProtocol, weight: CouplingWeight, *, overwrite: bool = False
+    ) -> None: ...
+    def offset(self) -> int: ...
+    def all_nodes(self) -> Iterable[NodeProtocol]: ...
+
+class NodeNX(NodeProtocol):
+    EPI: EPIValue
+    vf: StructuralFrequency
+    theta: Phase
+    Si: SenseIndex
+    epi_kind: str
+    dnfr: DeltaNFR
+    d2EPI: SecondDerivativeEPI
+    G: TNFRGraph
+    n: NodeId
+    graph: MutableMapping[str, Any]
+    state_projector: StateProjector
+    enable_math_validation: bool
+    hilbert_space: HilbertSpace
+    coherence_operator: CoherenceOperator | None
+    frequency_operator: FrequencyOperator | None
+    coherence_threshold: float | None
+    validator: NFRValidator | None
+    rng: np.random.Generator | None
+    def __init__(
+        self,
+        G: TNFRGraph,
+        n: NodeId,
+        *,
+        state_projector: StateProjector | None = None,
+        enable_math_validation: bool | None = None,
+        hilbert_space: HilbertSpace | None = None,
+        coherence_operator: CoherenceOperator | None = None,
+        coherence_dim: int | None = None,
+        coherence_spectrum: Sequence[float] | np.ndarray | None = None,
+        coherence_c_min: float | None = None,
+        frequency_operator: FrequencyOperator | None = None,
+        frequency_matrix: Sequence[Sequence[complex]] | np.ndarray | None = None,
+        coherence_threshold: float | None = None,
+        validator: NFRValidator | None = None,
+        rng: np.random.Generator | None = None,
+    ) -> None: ...
+    @classmethod
+    def from_graph(cls, G: TNFRGraph, n: NodeId) -> NodeNX: ...
+    def neighbors(self) -> Iterable[NodeId]: ...
+    def has_edge(self, other: NodeProtocol) -> bool: ...
+    def add_edge(
+        self, other: NodeProtocol, weight: CouplingWeight, *, overwrite: bool = False
+    ) -> None: ...
+    def offset(self) -> int: ...
+    def all_nodes(self) -> Iterable[NodeProtocol]: ...
+    def run_sequence_with_validation(
+        self,
+        ops: Iterable[Callable[[TNFRGraph, NodeId], None]],
+        *,
+        projector: StateProjector | None = None,
+        hilbert_space: HilbertSpace | None = None,
+        coherence_operator: CoherenceOperator | None = None,
+        coherence_dim: int | None = None,
+        coherence_spectrum: Sequence[float] | np.ndarray | None = None,
+        coherence_c_min: float | None = None,
+        coherence_threshold: float | None = None,
+        frequency_operator: FrequencyOperator | None = None,
+        frequency_matrix: Sequence[Sequence[complex]] | np.ndarray | None = None,
+        validator: NFRValidator | None = None,
+        enforce_frequency_positivity: bool | None = None,
+        enable_validation: bool | None = None,
+        rng: np.random.Generator | None = None,
+        log_metrics: bool = False,
+    ) -> dict[str, Any]: ...

tnfr/observers.py

@@ -1,149 +1,274 @@
-"""
-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 constants import ALIAS_DNFR, ALIAS_EPI, ALIAS_THETA, ALIAS_dEPI
-from helpers import _get_attr, list_mean, register_callback
+import statistics
+from collections.abc import Mapping
+from functools import partial
+from statistics import StatisticsError, pvariance
+
+from .alias import get_theta_attr
+from .utils import CallbackEvent, callback_manager
+from .config.constants import GLYPH_GROUPS
+from .gamma import kuramoto_R_psi
+from .glyph_history import (
+    append_metric,
+    count_glyphs,
+    ensure_history,
+)
+from .utils import angle_diff
+from .metrics.common import compute_coherence
+from .types import Glyph, GlyphLoadDistribution, TNFRGraph
+from .utils import (
+    get_logger,
+    get_numpy,
+    mix_groups,
+    normalize_counter,
+)
+from .validation import validate_window
+from .telemetry import ensure_nu_f_telemetry, record_nu_f_window
+
+__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
+
 
 # -------------------------
-# Observador estándar Γ(R)
+# Standard Γ(R) observer
 # -------------------------
-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_before(G, ctx):
-    _std_log(G, "before", ctx)
-
-def std_after(G, ctx):
-    _std_log(G, "after", ctx)
-
-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")
+def _std_log(kind: str, G: TNFRGraph, ctx: Mapping[str, object]) -> None:
+    """Store compact events in ``history['events']``."""
+    h = ensure_history(G)
+    append_metric(h, "events", (kind, dict(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"),
+    CallbackEvent.CACHE_METRICS.value: partial(_std_log, "cache"),
+}
+
+_REORG_STATE_KEY = "_std_observer_reorg"
+
+
+def _resolve_reorg_state(G: TNFRGraph) -> dict[str, object]:
+    state = G.graph.get(_REORG_STATE_KEY)
+    if not isinstance(state, dict):
+        state = {}
+        G.graph[_REORG_STATE_KEY] = state
+    return state
+
+
+def _before_step_reorg(G: TNFRGraph, ctx: Mapping[str, object] | None) -> None:
+    """Capture structural time metadata before the step starts."""
+
+    ensure_nu_f_telemetry(G, confidence_level=None)
+    state = _resolve_reorg_state(G)
+    step_idx = ctx.get("step") if ctx else None
+    try:
+        state["step"] = int(step_idx) if step_idx is not None else None
+    except (TypeError, ValueError):
+        state["step"] = None
+    start_t = float(G.graph.get("_t", 0.0))
+    state["start_t"] = start_t
+    dt_raw = ctx.get("dt") if ctx else None
+    try:
+        state["dt"] = float(dt_raw) if dt_raw is not None else None
+    except (TypeError, ValueError):
+        state["dt"] = None
+
+
+def _after_step_reorg(G: TNFRGraph, ctx: Mapping[str, object] | None) -> None:
+    """Record the reorganisation window for νf telemetry."""
+
+    state = _resolve_reorg_state(G)
+    pending_step = state.get("step")
+    ctx_step = ctx.get("step") if ctx else None
+    if pending_step is not None and ctx_step is not None and pending_step != ctx_step:
+        # Ignore mismatched callbacks to avoid double counting.
+        return
+
+    try:
+        start_t = float(state.get("start_t", float(G.graph.get("_t", 0.0))))
+    except (TypeError, ValueError):
+        start_t = float(G.graph.get("_t", 0.0))
+    end_t = float(G.graph.get("_t", start_t))
+    dt_raw = state.get("dt")
+    try:
+        duration = float(dt_raw) if dt_raw is not None else end_t - start_t
+    except (TypeError, ValueError):
+        duration = end_t - start_t
+    if duration <= 0.0:
+        duration = end_t - start_t
+    if duration <= 0.0:
+        return
+
+    stable_frac = ctx.get("stable_frac") if ctx else None
+    if stable_frac is None:
+        hist = ensure_history(G)
+        series = hist.get("stable_frac", [])
+        stable_frac = series[-1] if series else None
+    try:
+        stable_frac_f = float(stable_frac) if stable_frac is not None else None
+    except (TypeError, ValueError):
+        stable_frac_f = None
+    total_nodes = G.number_of_nodes()
+    if stable_frac_f is None:
+        reorganisations = total_nodes
+    else:
+        frac = min(max(stable_frac_f, 0.0), 1.0)
+        stable_nodes = int(round(frac * total_nodes))
+        reorganisations = max(total_nodes - stable_nodes, 0)
+
+    record_nu_f_window(
+        G,
+        reorganisations,
+        duration,
+        start=start_t,
+        end=end_t,
+    )
+    state["last_duration"] = duration
+    state["last_reorganisations"] = reorganisations
+    state["last_end_t"] = end_t
+    state["step"] = None
+
+
+def attach_standard_observer(G: TNFRGraph) -> TNFRGraph:
+    """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)
+    callback_manager.register_callback(
+        G,
+        CallbackEvent.BEFORE_STEP.value,
+        _before_step_reorg,
+        name="std_reorg_before",
+    )
+    callback_manager.register_callback(
+        G,
+        CallbackEvent.AFTER_STEP.value,
+        _after_step_reorg,
+        name="std_reorg_after",
+    )
+    ensure_nu_f_telemetry(G, confidence_level=None)
+    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: TNFRGraph) -> bool:
+    """Return ``True`` when the graph has nodes."""
+    return bool(G.number_of_nodes())
+
+
+def kuramoto_metrics(G: TNFRGraph) -> 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 phase_sync(
+    G: TNFRGraph,
+    R: float | None = None,
+    psi: float | None = None,
+) -> float:
+    """Return a [0, 1] synchrony index derived from phase dispersion."""
 
-def sincronía_fase(G) -> float:
-    X = list(math.cos(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes())
-    Y = list(math.sin(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes())
-    if not X:
+    if not _ensure_nodes(G):
         return 1.0
-    import math
-    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 psi is None:
+        _, psi = kuramoto_metrics(G)
+
+    def _theta(nd: Mapping[str, object]) -> float:
+        value = get_theta_attr(nd, 0.0)
+        return float(value) if value is not None else 0.0
+
+    diffs = (angle_diff(_theta(data), 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: TNFRGraph, 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: TNFRGraph, window: int | None = None) -> GlyphLoadDistribution:
+    """Return distribution of structural operators applied in the network.
+
+    Analyzes which structural operator symbols (glyphs) have been applied to
+    nodes in the network over a given time window.
+
+    - ``window``: if provided, count only the last ``window`` events per node;
+      otherwise use :data:`DEFAULT_GLYPH_LOAD_SPAN`.
+
+    Returns a dict with proportions per structural operator symbol 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.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_raw, 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["_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 {"_count": 0.0}
+    dist = mix_groups(dist_raw, GLYPH_GROUPS)
+    glyph_dist: GlyphLoadDistribution = {}
+    for key, value in dist.items():
+        try:
+            glyph_key: Glyph | str = Glyph(key)
+        except ValueError:
+            glyph_key = key
+        glyph_dist[glyph_key] = value
+    glyph_dist["_count"] = float(count)
+    return glyph_dist
+
+
+def wbar(G: TNFRGraph, window: int | None = None) -> float:
+    """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)
+        # fallback: instantaneous coherence
+        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/observers.pyi

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Final
+
+from .types import GlyphLoadDistribution, TNFRGraph
+
+__all__: tuple[str, ...]
+
+DEFAULT_GLYPH_LOAD_SPAN: Final[int]
+DEFAULT_WBAR_SPAN: Final[int]
+
+def _std_log(kind: str, G: TNFRGraph, ctx: Mapping[str, object]) -> None: ...
+def attach_standard_observer(G: TNFRGraph) -> TNFRGraph: ...
+def _ensure_nodes(G: TNFRGraph) -> bool: ...
+def kuramoto_metrics(G: TNFRGraph) -> tuple[float, float]: ...
+def phase_sync(
+    G: TNFRGraph,
+    R: float | None = ...,
+    psi: float | None = ...,
+) -> float: ...
+def kuramoto_order(
+    G: TNFRGraph,
+    R: float | None = ...,
+    psi: float | None = ...,
+) -> float: ...
+def glyph_load(
+    G: TNFRGraph,
+    window: int | None = ...,
+) -> GlyphLoadDistribution: ...
+def wbar(G: TNFRGraph, window: int | None = ...) -> float: ...