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

tnfr/observers.pyi

@@ -0,0 +1,46 @@
+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,6 +1,7 @@
 """Orchestrate the canonical simulation."""
 
 from __future__ import annotations
+
 from collections import deque
 from typing import TYPE_CHECKING
 
@@ -10,16 +11,16 @@ from .dynamics import step as _step, run as _run
 from .dynamics import default_compute_delta_nfr
 from .initialization import init_node_attrs
 from .glyph_history import append_metric
-from .import_utils import cached_import
+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,7 +44,7 @@ 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"]
@@ -59,7 +60,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",
@@ -76,12 +77,12 @@ def preparar_red(
             "phase_disr": deque(maxlen=ph_len),
         }
     )
-    G.graph.setdefault("history", history)
-    # Memoria global de REMESH
+    history_ref = G.graph.setdefault("history", history)
+    # 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 +96,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 +111,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:

tnfr/ontosim.pyi

@@ -0,0 +1,33 @@
+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: ...

tnfr/operators/__init__.py

@@ -1,7 +1,9 @@
 """Network operators."""
 
 from __future__ import annotations
-from typing import Any, TYPE_CHECKING, Callable
+
+from collections.abc import Callable, Iterator
+from typing import Any, TYPE_CHECKING
 import math
 import heapq
 from itertools import islice
@@ -12,11 +14,12 @@ from ..constants import DEFAULTS, get_aliases, get_param
 
 from ..helpers.numeric import angle_diff
 from ..metrics.trig import neighbor_phase_mean
-from ..import_utils import get_nodonx
+from ..utils import get_nodenx
 from ..rng import make_rng
 from tnfr import glyph_history
-from ..types import Glyph
+from ..types import EPIValue, Glyph, NodeId, TNFRGraph
 
+from . import definitions as _definitions
 from .jitter import (
     JitterCache,
     JitterCacheManager,
@@ -24,14 +27,38 @@ from .jitter import (
     reset_jitter_manager,
     random_jitter,
 )
+from .registry import OPERATORS, discover_operators, get_operator_class
 from .remesh import (
     apply_network_remesh,
     apply_topological_remesh,
     apply_remesh_if_globally_stable,
 )
 
+_remesh_doc = (
+    "Trigger a remesh once the stability window is satisfied.\n\n"
+    "Parameters\n----------\n"
+    "stable_step_window : int | None\n"
+    "    Number of consecutive stable steps required before remeshing.\n"
+    "    Only the English keyword 'stable_step_window' is supported."
+)
+if apply_remesh_if_globally_stable.__doc__:
+    apply_remesh_if_globally_stable.__doc__ += "\n\n" + _remesh_doc
+else:
+    apply_remesh_if_globally_stable.__doc__ = _remesh_doc
+
+discover_operators()
+
+_DEFINITION_EXPORTS = {
+    name: getattr(_definitions, name)
+    for name in getattr(_definitions, "__all__", ())
+}
+globals().update(_DEFINITION_EXPORTS)
+
 if TYPE_CHECKING:  # pragma: no cover - type checking only
-    from ..node import NodoProtocol
+    from ..node import NodeProtocol
+
+GlyphFactors = dict[str, Any]
+GlyphOperation = Callable[["NodeProtocol", GlyphFactors], None]
 
 ALIAS_EPI = get_aliases("EPI")
 
@@ -49,15 +76,20 @@ __all__ = [
     "apply_network_remesh",
     "apply_topological_remesh",
     "apply_remesh_if_globally_stable",
+    "OPERATORS",
+    "discover_operators",
+    "get_operator_class",
 ]
 
+__all__.extend(_DEFINITION_EXPORTS.keys())
+
 
-def get_glyph_factors(node: NodoProtocol) -> dict[str, Any]:
+def get_glyph_factors(node: NodeProtocol) -> GlyphFactors:
     """Return glyph factors for ``node`` with defaults."""
     return node.graph.get("GLYPH_FACTORS", DEFAULTS["GLYPH_FACTORS"].copy())
 
 
-def get_factor(gf: dict[str, Any], key: str, default: float) -> float:
+def get_factor(gf: GlyphFactors, key: str, default: float) -> float:
     """Return ``gf[key]`` as ``float`` with ``default`` fallback."""
     return float(gf.get(key, default))
 
@@ -67,7 +99,7 @@ def get_factor(gf: dict[str, Any], key: str, default: float) -> float:
 # -------------------------
 
 
-def get_neighbor_epi(node: NodoProtocol) -> tuple[list[NodoProtocol], float]:
+def get_neighbor_epi(node: NodeProtocol) -> tuple[list[NodeProtocol], EPIValue]:
     """Return neighbour list and their mean ``EPI`` without mutating ``node``."""
 
     epi = node.EPI
@@ -98,11 +130,11 @@ def get_neighbor_epi(node: NodoProtocol) -> tuple[list[NodoProtocol], float]:
             return [], epi
         epi_bar = total / count if count else float(epi)
         if needs_conversion:
-            NodoNX = get_nodonx()
-            if NodoNX is None:
-                raise ImportError("NodoNX is unavailable")
+            NodeNX = get_nodenx()
+            if NodeNX is None:
+                raise ImportError("NodeNX is unavailable")
             neigh = [
-                v if hasattr(v, "EPI") else NodoNX.from_graph(node.G, v)
+                v if hasattr(v, "EPI") else NodeNX.from_graph(node.G, v)
                 for v in neigh
             ]
     else:
@@ -115,7 +147,7 @@ def get_neighbor_epi(node: NodoProtocol) -> tuple[list[NodoProtocol], float]:
 
 
 def _determine_dominant(
-    neigh: list[NodoProtocol], default_kind: str
+    neigh: list[NodeProtocol], default_kind: str
 ) -> tuple[str, float]:
     """Return dominant ``epi_kind`` among ``neigh`` and its absolute ``EPI``."""
     best_kind: str | None = None
@@ -131,7 +163,7 @@ def _determine_dominant(
 
 
 def _mix_epi_with_neighbors(
-    node: NodoProtocol, mix: float, default_glyph: Glyph | str
+    node: NodeProtocol, mix: float, default_glyph: Glyph | str
 ) -> tuple[float, str]:
     """Mix ``EPI`` of ``node`` with the mean of its neighbours."""
     default_kind = (
@@ -156,22 +188,22 @@ def _mix_epi_with_neighbors(
     return epi_bar, final
 
 
-def _op_AL(node: NodoProtocol, gf: dict[str, Any]) -> None:  # AL — Emisión
+def _op_AL(node: NodeProtocol, gf: GlyphFactors) -> None:  # AL — Emission
     f = get_factor(gf, "AL_boost", 0.05)
     node.EPI = node.EPI + f
 
 
-def _op_EN(node: NodoProtocol, gf: dict[str, Any]) -> None:  # EN — Recepción
+def _op_EN(node: NodeProtocol, gf: GlyphFactors) -> None:  # EN — Reception
     mix = get_factor(gf, "EN_mix", 0.25)
     _mix_epi_with_neighbors(node, mix, Glyph.EN)
 
 
-def _op_IL(node: NodoProtocol, gf: dict[str, Any]) -> None:  # IL — Coherencia
+def _op_IL(node: NodeProtocol, gf: GlyphFactors) -> None:  # IL — Coherence
     factor = get_factor(gf, "IL_dnfr_factor", 0.7)
     node.dnfr = factor * getattr(node, "dnfr", 0.0)
 
 
-def _op_OZ(node: NodoProtocol, gf: dict[str, Any]) -> None:  # OZ — Disonancia
+def _op_OZ(node: NodeProtocol, gf: GlyphFactors) -> None:  # OZ — Dissonance
     factor = get_factor(gf, "OZ_dnfr_factor", 1.3)
     dnfr = getattr(node, "dnfr", 0.0)
     if bool(node.graph.get("OZ_NOISE_MODE", False)):
@@ -184,13 +216,13 @@ def _op_OZ(node: NodoProtocol, gf: dict[str, Any]) -> None:  # OZ — Disonancia
         node.dnfr = factor * dnfr if abs(dnfr) > 1e-9 else 0.1
 
 
-def _um_candidate_iter(node: NodoProtocol):
+def _um_candidate_iter(node: NodeProtocol) -> Iterator[NodeProtocol]:
     sample_ids = node.graph.get("_node_sample")
     if sample_ids is not None and hasattr(node, "G"):
-        NodoNX = get_nodonx()
-        if NodoNX is None:
-            raise ImportError("NodoNX is unavailable")
-        base = (NodoNX.from_graph(node.G, j) for j in sample_ids)
+        NodeNX = get_nodenx()
+        if NodeNX is None:
+            raise ImportError("NodeNX is unavailable")
+        base = (NodeNX.from_graph(node.G, j) for j in sample_ids)
     else:
         base = node.all_nodes()
     for j in base:
@@ -203,12 +235,12 @@ def _um_candidate_iter(node: NodoProtocol):
 
 
 def _um_select_candidates(
-    node: NodoProtocol,
-    candidates,
+    node: NodeProtocol,
+    candidates: Iterator[NodeProtocol],
     limit: int,
     mode: str,
     th: float,
-):
+) -> list[NodeProtocol]:
     """Select a subset of ``candidates`` for UM coupling."""
     rng = make_rng(int(node.graph.get("RANDOM_SEED", 0)), node.offset(), node.G)
 
@@ -232,7 +264,7 @@ def _um_select_candidates(
     return reservoir
 
 
-def _op_UM(node: NodoProtocol, gf: dict[str, Any]) -> None:  # UM — Coupling
+def _op_UM(node: NodeProtocol, gf: GlyphFactors) -> None:  # UM — Coupling
     k = get_factor(gf, "UM_theta_push", 0.25)
     th = node.theta
     thL = neighbor_phase_mean(node)
@@ -269,12 +301,12 @@ def _op_UM(node: NodoProtocol, gf: dict[str, Any]) -> None:  # UM — Coupling
                 node.add_edge(j, compat)
 
 
-def _op_RA(node: NodoProtocol, gf: dict[str, Any]) -> None:  # RA — Resonancia
+def _op_RA(node: NodeProtocol, gf: GlyphFactors) -> None:  # RA — Resonance
     diff = get_factor(gf, "RA_epi_diff", 0.15)
     _mix_epi_with_neighbors(node, diff, Glyph.RA)
 
 
-def _op_SHA(node: NodoProtocol, gf: dict[str, Any]) -> None:  # SHA — Silencio
+def _op_SHA(node: NodeProtocol, gf: GlyphFactors) -> None:  # SHA — Silence
     factor = get_factor(gf, "SHA_vf_factor", 0.85)
     node.vf = factor * node.vf
 
@@ -284,12 +316,12 @@ factor_nul = 0.85
 _SCALE_FACTORS = {Glyph.VAL: factor_val, Glyph.NUL: factor_nul}
 
 
-def _op_scale(node: NodoProtocol, factor: float) -> None:
+def _op_scale(node: NodeProtocol, factor: float) -> None:
     node.vf *= factor
 
 
-def _make_scale_op(glyph: Glyph):
-    def _op(node: NodoProtocol, gf: dict[str, Any]) -> None:
+def _make_scale_op(glyph: Glyph) -> GlyphOperation:
+    def _op(node: NodeProtocol, gf: GlyphFactors) -> None:
         key = "VAL_scale" if glyph is Glyph.VAL else "NUL_scale"
         default = _SCALE_FACTORS[glyph]
         factor = get_factor(gf, key, default)
@@ -299,22 +331,22 @@ def _make_scale_op(glyph: Glyph):
 
 
 def _op_THOL(
-    node: NodoProtocol, gf: dict[str, Any]
-) -> None:  # THOL — Autoorganización
+    node: NodeProtocol, gf: GlyphFactors
+) -> None:  # THOL — Self-organization
     a = get_factor(gf, "THOL_accel", 0.10)
     node.dnfr = node.dnfr + a * getattr(node, "d2EPI", 0.0)
 
 
 def _op_ZHIR(
-    node: NodoProtocol, gf: dict[str, Any]
-) -> None:  # ZHIR — Mutación
+    node: NodeProtocol, gf: GlyphFactors
+) -> None:  # ZHIR — Mutation
     shift = get_factor(gf, "ZHIR_theta_shift", math.pi / 2)
     node.theta = node.theta + shift
 
 
 def _op_NAV(
-    node: NodoProtocol, gf: dict[str, Any]
-) -> None:  # NAV — Transición
+    node: NodeProtocol, gf: GlyphFactors
+) -> None:  # NAV — Transition
     dnfr = node.dnfr
     vf = node.vf
     eta = get_factor(gf, "NAV_eta", 0.5)
@@ -334,14 +366,14 @@ def _op_NAV(
 
 
 def _op_REMESH(
-    node: NodoProtocol, gf: dict[str, Any] | None = None
-) -> None:  # REMESH — aviso
+    node: NodeProtocol, gf: GlyphFactors | None = None
+) -> None:  # REMESH — advisory
     step_idx = glyph_history.current_step_idx(node)
     last_warn = node.graph.get("_remesh_warn_step", None)
     if last_warn != step_idx:
         msg = (
-            "REMESH es a escala de red. Usa apply_remesh_if_globally_"
-            "stable(G) o apply_network_remesh(G)."
+            "REMESH operates at network scale. Use apply_remesh_if_globally_"
+            "stable(G) or apply_network_remesh(G)."
         )
         hist = glyph_history.ensure_history(node)
         glyph_history.append_metric(
@@ -357,7 +389,7 @@ def _op_REMESH(
 # Dispatcher
 # -------------------------
 
-GLYPH_OPERATIONS: dict[Glyph, Callable[["NodoProtocol", dict[str, Any]], None]] = {
+GLYPH_OPERATIONS: dict[Glyph, GlyphOperation] = {
     Glyph.AL: _op_AL,
     Glyph.EN: _op_EN,
     Glyph.IL: _op_IL,
@@ -375,9 +407,9 @@ GLYPH_OPERATIONS: dict[Glyph, Callable[["NodoProtocol", dict[str, Any]], None]]
 
 
 def apply_glyph_obj(
-    node: NodoProtocol, glyph: Glyph | str, *, window: int | None = None
+    node: NodeProtocol, glyph: Glyph | str, *, window: int | None = None
 ) -> None:
-    """Apply ``glyph`` to an object satisfying :class:`NodoProtocol`."""
+    """Apply ``glyph`` to an object satisfying :class:`NodeProtocol`."""
 
     try:
         g = glyph if isinstance(glyph, Glyph) else Glyph(str(glyph))
@@ -392,15 +424,15 @@ def apply_glyph_obj(
                 {
                     "step": step_idx,
                     "node": getattr(node, "n", None),
-                    "msg": f"glyph desconocido: {glyph}",
+                    "msg": f"unknown glyph: {glyph}",
                 },
             ),
         )
-        raise ValueError(f"glyph desconocido: {glyph}")
+        raise ValueError(f"unknown glyph: {glyph}")
 
     op = GLYPH_OPERATIONS.get(g)
     if op is None:
-        raise ValueError(f"glyph sin operador: {g}")
+        raise ValueError(f"glyph has no registered operator: {g}")
     if window is None:
         window = int(get_param(node, "GLYPH_HYSTERESIS_WINDOW"))
     gf = get_glyph_factors(node)
@@ -410,11 +442,11 @@ def apply_glyph_obj(
 
 
 def apply_glyph(
-    G, n, glyph: Glyph | str, *, window: int | None = None
+    G: TNFRGraph, n: NodeId, glyph: Glyph | str, *, window: int | None = None
 ) -> None:
     """Adapter to operate on ``networkx`` graphs."""
-    NodoNX = get_nodonx()
-    if NodoNX is None:
-        raise ImportError("NodoNX is unavailable")
-    node = NodoNX(G, n)
+    NodeNX = get_nodenx()
+    if NodeNX is None:
+        raise ImportError("NodeNX is unavailable")
+    node = NodeNX(G, n)
     apply_glyph_obj(node, glyph, window=window)

tnfr/operators/__init__.pyi

@@ -0,0 +1,31 @@
+from typing import Any
+
+Operator: Any
+Emission: Any
+Reception: Any
+Coherence: Any
+Dissonance: Any
+Coupling: Any
+Resonance: Any
+Silence: Any
+Expansion: Any
+Contraction: Any
+SelfOrganization: Any
+Mutation: Any
+Transition: Any
+Recursivity: Any
+GLYPH_OPERATIONS: Any
+JitterCache: Any
+JitterCacheManager: Any
+OPERATORS: Any
+apply_glyph: Any
+apply_glyph_obj: Any
+apply_network_remesh: Any
+apply_remesh_if_globally_stable: Any
+apply_topological_remesh: Any
+discover_operators: Any
+get_glyph_factors: Any
+get_jitter_manager: Any
+get_neighbor_epi: Any
+random_jitter: Any
+reset_jitter_manager: Any