tnfr 4.5.2__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,28 +1,32 @@
 """Observer management."""
 
 from __future__ import annotations
-from functools import partial
+
 import statistics
+from collections.abc import Mapping
+from functools import partial
 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 .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 (
-    ensure_history,
-    count_glyphs,
     append_metric,
+    count_glyphs,
+    ensure_history,
 )
-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 .utils import angle_diff
 from .metrics.common import compute_coherence
-from .validators import validate_window
-
-ALIAS_THETA = get_aliases("THETA")
+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",
@@ -35,18 +39,16 @@ __all__ = (
     "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(kind: str, G, ctx: dict):
+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)))
@@ -56,25 +58,123 @@ _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 attach_standard_observer(G):
+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 _ensure_nodes(G) -> bool:
+def _ensure_nodes(G: TNFRGraph) -> bool:
     """Return ``True`` when the graph has nodes."""
     return bool(G.number_of_nodes())
 
 
-def kuramoto_metrics(G) -> tuple[float, float]:
+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
@@ -83,19 +183,23 @@ def kuramoto_metrics(G) -> tuple[float, float]:
     return kuramoto_R_psi(G)
 
 
-def phase_sync(G, R: float | None = None, psi: float | None = None) -> float:
+def phase_sync(
+    G: TNFRGraph,
+    R: float | None = None,
+    psi: float | None = None,
+) -> float:
+    """Return a [0, 1] synchrony index derived from phase dispersion."""
+
     if not _ensure_nodes(G):
         return 1.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)
-    )
+    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:
@@ -110,7 +214,7 @@ def phase_sync(G, R: float | None = None, psi: float | None = None) -> float:
 
 
 def kuramoto_order(
-    G, R: float | None = None, psi: float | None = None
+    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):
@@ -120,29 +224,40 @@ def kuramoto_order(
     return float(R)
 
 
-def glyph_load(G, window: int | None = None) -> dict:
-    """Return distribution of glyphs applied in the network.
+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 glyph and useful aggregates.
+
+    Returns a dict with proportions per structural operator symbol and useful aggregates.
     """
     if window == 0:
-        return {"_count": 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, count = normalize_counter(total)
+    dist_raw, count = normalize_counter(total)
     if count == 0:
-        return {"_count": 0}
-    dist = mix_groups(dist, GLYPH_GROUPS)
-    dist["_count"] = count
-    return dist
+        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, window: int | None = None) -> float:
+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
@@ -151,7 +266,7 @@ def wbar(G, window: int | None = None) -> float:
     hist = ensure_history(G)
     cs = list(hist.get("C_steps", []))
     if not cs:
-        # fallback: coherencia instantánea
+        # 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)

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

tnfr/ontosim.py

@@ -1,25 +1,27 @@
 """Orchestrate the canonical simulation."""
 
 from __future__ import annotations
+
 from collections import deque
 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 .utils import CallbackEvent
+from .constants import METRIC_DEFAULTS, get_param, inject_defaults
 from .dynamics import default_compute_delta_nfr
-from .initialization import init_node_attrs
+from .dynamics import run as _run
+from .dynamics import step as _step
 from .glyph_history import append_metric
-from .import_utils import cached_import
+from .initialization import init_node_attrs
+from .utils import cached_import
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx as nx  # type: ignore[import-untyped]
+    import networkx as nx
 
-# API de alto nivel
-__all__ = ("preparar_red", "step", "run")
+# High-level API exports
+__all__ = ("prepare_network", "step", "run")
 
 
-def preparar_red(
+def prepare_network(
     G: "nx.Graph",
     *,
     init_attrs: bool = True,
@@ -43,11 +45,9 @@ def preparar_red(
         from .constants import merge_overrides
 
         merge_overrides(G, **overrides)
-    # Inicializaciones blandas
+    # Initialize history buffers
     ph_len = int(
-        G.graph.get(
-            "PHASE_HISTORY_MAXLEN", METRIC_DEFAULTS["PHASE_HISTORY_MAXLEN"]
-        )
+        G.graph.get("PHASE_HISTORY_MAXLEN", METRIC_DEFAULTS["PHASE_HISTORY_MAXLEN"])
     )
     hist_keys = [
         "C_steps",
@@ -59,7 +59,7 @@ def preparar_red(
         "sense_sigma_mag",
         "sense_sigma_angle",
         "iota",
-        "glyph_load_estab",
+        "glyph_load_stabilizers",
         "glyph_load_disr",
         "Si_mean",
         "Si_hi_frac",
@@ -77,11 +77,11 @@ def preparar_red(
         }
     )
     G.graph.setdefault("history", history)
-    # Memoria global de REMESH
+    # Global REMESH memory
     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
+    # Auto-attach the standard observer when requested
     if G.graph.get("ATTACH_STD_OBSERVER", False):
         attach_standard_observer = cached_import(
             "tnfr.observers",
@@ -95,7 +95,7 @@ def preparar_red(
                 "_callback_errors",
                 {"event": "attach_std_observer", "error": "ImportError"},
             )
-    # Hook explícito para ΔNFR (se puede sustituir luego con
+    # Explicit hook for ΔNFR (can later be replaced with
     # 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")
@@ -110,8 +110,8 @@ def preparar_red(
     )
     G.graph.setdefault(
         "_CALLBACKS_DOC",
-        "Interfaz Γ(R): registrar pares (name, func) con firma (G, ctx) "
-        "en callbacks['before_step'|'after_step'|'on_remesh']",
+        "Γ(R) interface: register (name, func) pairs with signature (G, ctx) "
+        "in callbacks['before_step'|'after_step'|'on_remesh']",
     )
 
     if init_attrs:
@@ -126,6 +126,8 @@ def step(
     use_Si: bool = True,
     apply_glyphs: bool = True,
 ) -> None:
+    """Advance the ontosim runtime by a single step."""
+
     _step(G, dt=dt, use_Si=use_Si, apply_glyphs=apply_glyphs)
 
 
@@ -137,4 +139,6 @@ def run(
     use_Si: bool = True,
     apply_glyphs: bool = True,
 ) -> None:
+    """Advance the ontosim runtime ``steps`` times with optional overrides."""
+
     _run(G, steps=steps, dt=dt, use_Si=use_Si, apply_glyphs=apply_glyphs)

tnfr/ontosim.pyi

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from .types import TNFRConfigValue, TNFRGraph
+
+__all__: tuple[str, ...]
+
+def prepare_network(
+    G: TNFRGraph,
+    *,
+    init_attrs: bool = True,
+    override_defaults: bool = False,
+    **overrides: TNFRConfigValue,
+) -> TNFRGraph: ...
+def step(
+    G: TNFRGraph,
+    *,
+    dt: float | None = None,
+    use_Si: bool = True,
+    apply_glyphs: bool = True,
+) -> None: ...
+def run(
+    G: TNFRGraph,
+    steps: int,
+    *,
+    dt: float | None = None,
+    use_Si: bool = True,
+    apply_glyphs: bool = True,
+) -> None: ...