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

tnfr/node.py

@@ -1,13 +1,24 @@
 """Node utilities and structures for TNFR graphs."""
 
 from __future__ import annotations
-from typing import Iterable, MutableMapping, Optional, Protocol, TypeVar
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    MutableMapping,
+    Optional,
+    Protocol,
+    SupportsFloat,
+    TypeVar,
+)
 from collections.abc import Hashable
 import math
+from dataclasses import dataclass
 
 from .constants import get_aliases
 from .alias import (
     get_attr,
+    get_theta_attr,
     get_attr_str,
     set_attr,
     set_attr_str,
@@ -15,12 +26,23 @@ from .alias import (
     set_dnfr,
     set_theta,
 )
-from .cache import (
+from .types import (
+    CouplingWeight,
+    DeltaNFR,
+    EPIValue,
+    NodeId,
+    Phase,
+    SecondDerivativeEPI,
+    SenseIndex,
+    StructuralFrequency,
+    TNFRGraph,
+)
+from .utils import (
     cached_node_list,
     ensure_node_offset_map,
     increment_edge_version,
+    supports_add_edge,
 )
-from .graph_utils import supports_add_edge
 from .locking import get_lock
 
 ALIAS_EPI = get_aliases("EPI")
@@ -31,88 +53,77 @@ ALIAS_EPI_KIND = get_aliases("EPI_KIND")
 ALIAS_DNFR = get_aliases("DNFR")
 ALIAS_D2EPI = get_aliases("D2EPI")
 
-# Mapping of NodoNX attribute specifications used to generate property
-# descriptors. Each entry defines the keyword arguments passed to
-# ``_nx_attr_property`` for a given attribute name.
-ATTR_SPECS: dict[str, dict] = {
-    "EPI": {"aliases": ALIAS_EPI},
-    "vf": {
-        "aliases": ALIAS_VF,
-        "setter": set_vf,
-        "use_graph_setter": True,
-    },
-    "theta": {
-        "aliases": ALIAS_THETA,
-        "setter": set_theta,
-        "use_graph_setter": True,
-    },
-    "Si": {"aliases": ALIAS_SI},
-    "epi_kind": {
-        "aliases": ALIAS_EPI_KIND,
-        "default": "",
-        "getter": get_attr_str,
-        "setter": set_attr_str,
-        "to_python": str,
-        "to_storage": str,
-    },
-    "dnfr": {
-        "aliases": ALIAS_DNFR,
-        "setter": set_dnfr,
-        "use_graph_setter": True,
-    },
-    "d2EPI": {"aliases": ALIAS_D2EPI},
-}
-
 T = TypeVar("T")
 
-__all__ = ("NodoNX", "NodoProtocol", "add_edge")
-
-
-def _nx_attr_property(
-    aliases: tuple[str, ...],
-    *,
-    default=0.0,
-    getter=get_attr,
-    setter=set_attr,
-    to_python=float,
-    to_storage=float,
-    use_graph_setter=False,
-):
-    """Generate ``NodoNX`` property descriptors.
-
-    Parameters
-    ----------
-    aliases:
-        Immutable tuple of aliases used to access the attribute in the
-        underlying ``networkx`` node.
-    default:
-        Value returned when the attribute is missing.
-    getter, setter:
-        Helper functions used to retrieve or store the value. ``setter`` can
-        either accept ``(mapping, aliases, value)`` or, when
-        ``use_graph_setter`` is ``True``, ``(G, n, value)``.
-    to_python, to_storage:
-        Conversion helpers applied when getting or setting the value,
-        respectively.
-    use_graph_setter:
-        Whether ``setter`` expects ``(G, n, value)`` instead of
-        ``(mapping, aliases, value)``.
+__all__ = ("NodeNX", "NodeProtocol", "add_edge")
+
+
+@dataclass(frozen=True)
+class AttrSpec:
+    """Configuration required to expose a ``networkx`` node attribute.
+
+    ``AttrSpec`` mirrors the defaults previously used by
+    :func:`_nx_attr_property` and centralises the descriptor generation
+    logic to keep a single source of truth for NodeNX attribute access.
     """
 
-    def fget(self) -> T:
-        return to_python(getter(self.G.nodes[self.n], aliases, default))
+    aliases: tuple[str, ...]
+    default: Any = 0.0
+    getter: Callable[[MutableMapping[str, Any], tuple[str, ...], Any], Any] = get_attr
+    setter: Callable[..., None] = set_attr
+    to_python: Callable[[Any], Any] = float
+    to_storage: Callable[[Any], Any] = float
+    use_graph_setter: bool = False
 
-    def fset(self, value: T) -> None:
-        value = to_storage(value)
-        if use_graph_setter:
-            setter(self.G, self.n, value)
-        else:
-            setter(self.G.nodes[self.n], aliases, value)
+    def build_property(self) -> property:
+        """Create the property descriptor for ``NodeNX`` attributes."""
+
+        def fget(instance: "NodeNX") -> T:
+            return self.to_python(
+                self.getter(instance.G.nodes[instance.n], self.aliases, self.default)
+            )
+
+        def fset(instance: "NodeNX", value: T) -> None:
+            value = self.to_storage(value)
+            if self.use_graph_setter:
+                self.setter(instance.G, instance.n, value)
+            else:
+                self.setter(instance.G.nodes[instance.n], self.aliases, value)
+
+        return property(fget, fset)
 
-    return property(fget, fset)
+
+# Mapping of NodeNX attribute specifications used to generate property
+# descriptors. Each entry defines the keyword arguments passed to
+# ``AttrSpec.build_property`` for a given attribute name.
+ATTR_SPECS: dict[str, AttrSpec] = {
+    "EPI": AttrSpec(aliases=ALIAS_EPI),
+    "vf": AttrSpec(aliases=ALIAS_VF, setter=set_vf, use_graph_setter=True),
+    "theta": AttrSpec(
+        aliases=ALIAS_THETA,
+        getter=lambda mapping, _aliases, default: get_theta_attr(mapping, default),
+        setter=set_theta,
+        use_graph_setter=True,
+    ),
+    "Si": AttrSpec(aliases=ALIAS_SI),
+    "epi_kind": AttrSpec(
+        aliases=ALIAS_EPI_KIND,
+        default="",
+        getter=get_attr_str,
+        setter=set_attr_str,
+        to_python=str,
+        to_storage=str,
+    ),
+    "dnfr": AttrSpec(aliases=ALIAS_DNFR, setter=set_dnfr, use_graph_setter=True),
+    "d2EPI": AttrSpec(aliases=ALIAS_D2EPI),
+}
 
 
-def _add_edge_common(n1, n2, weight) -> Optional[float]:
+def _add_edge_common(
+    n1: NodeId,
+    n2: NodeId,
+    weight: CouplingWeight | SupportsFloat | str,
+) -> Optional[CouplingWeight]:
     """Validate basic edge constraints.
 
     Returns the parsed weight if the edge can be added. ``None`` is returned
@@ -132,12 +143,12 @@ def _add_edge_common(n1, n2, weight) -> Optional[float]:
 
 
 def add_edge(
-    graph,
-    n1,
-    n2,
-    weight,
+    graph: TNFRGraph,
+    n1: NodeId,
+    n2: NodeId,
+    weight: CouplingWeight | SupportsFloat | str,
     overwrite: bool = False,
-):
+) -> None:
     """Add an edge between ``n1`` and ``n2`` in a ``networkx`` graph."""
 
     weight = _add_edge_common(n1, n2, weight)
@@ -154,60 +165,70 @@ def add_edge(
     increment_edge_version(graph)
 
 
-class NodoProtocol(Protocol):
+class NodeProtocol(Protocol):
     """Minimal protocol for TNFR nodes."""
 
-    EPI: float
-    vf: float
-    theta: float
-    Si: float
+    EPI: EPIValue
+    vf: StructuralFrequency
+    theta: Phase
+    Si: SenseIndex
     epi_kind: str
-    dnfr: float
-    d2EPI: float
-    graph: dict[str, object]
+    dnfr: DeltaNFR
+    d2EPI: SecondDerivativeEPI
+    graph: MutableMapping[str, Any]
 
-    def neighbors(self) -> Iterable[NodoProtocol | Hashable]: ...
+    def neighbors(self) -> Iterable[NodeProtocol | Hashable]:
+        ...
 
-    def _glyph_storage(self) -> MutableMapping[str, object]: ...
+    def _glyph_storage(self) -> MutableMapping[str, object]:
+        ...
 
-    def has_edge(self, other: "NodoProtocol") -> bool: ...
+    def has_edge(self, other: "NodeProtocol") -> bool:
+        ...
 
     def add_edge(
-        self, other: "NodoProtocol", weight: float, *, overwrite: bool = False
-    ) -> None: ...
+        self,
+        other: NodeProtocol,
+        weight: CouplingWeight,
+        *,
+        overwrite: bool = False,
+    ) -> None:
+        ...
 
-    def offset(self) -> int: ...
+    def offset(self) -> int:
+        ...
 
-    def all_nodes(self) -> Iterable["NodoProtocol"]: ...
+    def all_nodes(self) -> Iterable[NodeProtocol]:
+        ...
 
 
-class NodoNX(NodoProtocol):
+class NodeNX(NodeProtocol):
     """Adapter for ``networkx`` nodes."""
 
-    # Statically defined property descriptors for ``NodoNX`` attributes.
+    # Statically defined property descriptors for ``NodeNX`` attributes.
     # Declaring them here makes the attributes discoverable by type checkers
     # and IDEs, avoiding the previous runtime ``setattr`` loop.
-    EPI: float = _nx_attr_property(**ATTR_SPECS["EPI"])
-    vf: float = _nx_attr_property(**ATTR_SPECS["vf"])
-    theta: float = _nx_attr_property(**ATTR_SPECS["theta"])
-    Si: float = _nx_attr_property(**ATTR_SPECS["Si"])
-    epi_kind: str = _nx_attr_property(**ATTR_SPECS["epi_kind"])
-    dnfr: float = _nx_attr_property(**ATTR_SPECS["dnfr"])
-    d2EPI: float = _nx_attr_property(**ATTR_SPECS["d2EPI"])
-
-    def __init__(self, G, n):
-        self.G = G
-        self.n = n
-        self.graph = G.graph
+    EPI: EPIValue = ATTR_SPECS["EPI"].build_property()
+    vf: StructuralFrequency = ATTR_SPECS["vf"].build_property()
+    theta: Phase = ATTR_SPECS["theta"].build_property()
+    Si: SenseIndex = ATTR_SPECS["Si"].build_property()
+    epi_kind: str = ATTR_SPECS["epi_kind"].build_property()
+    dnfr: DeltaNFR = ATTR_SPECS["dnfr"].build_property()
+    d2EPI: SecondDerivativeEPI = ATTR_SPECS["d2EPI"].build_property()
+
+    def __init__(self, G: TNFRGraph, n: NodeId) -> None:
+        self.G: TNFRGraph = G
+        self.n: NodeId = n
+        self.graph: MutableMapping[str, Any] = G.graph
         G.graph.setdefault("_node_cache", {})[n] = self
 
-    def _glyph_storage(self):
+    def _glyph_storage(self) -> MutableMapping[str, Any]:
         return self.G.nodes[self.n]
 
     @classmethod
-    def from_graph(cls, G, n):
-        """Return cached ``NodoNX`` for ``(G, n)`` with thread safety."""
-        lock = get_lock(f"nodonx_cache_{id(G)}")
+    def from_graph(cls, G: TNFRGraph, n: NodeId) -> "NodeNX":
+        """Return cached ``NodeNX`` for ``(G, n)`` with thread safety."""
+        lock = get_lock(f"node_nx_cache_{id(G)}")
         with lock:
             cache = G.graph.setdefault("_node_cache", {})
             node = cache.get(n)
@@ -215,23 +236,27 @@ class NodoNX(NodoProtocol):
                 node = cls(G, n)
             return node
 
-    def neighbors(self) -> Iterable[Hashable]:
+    def neighbors(self) -> Iterable[NodeId]:
         """Iterate neighbour identifiers (IDs).
 
         Wrap each resulting ID with :meth:`from_graph` to obtain the cached
-        ``NodoNX`` instance when actual node objects are required.
+        ``NodeNX`` instance when actual node objects are required.
         """
         return self.G.neighbors(self.n)
 
-    def has_edge(self, other: NodoProtocol) -> bool:
-        if isinstance(other, NodoNX):
+    def has_edge(self, other: NodeProtocol) -> bool:
+        if isinstance(other, NodeNX):
             return self.G.has_edge(self.n, other.n)
         raise NotImplementedError
 
     def add_edge(
-        self, other: NodoProtocol, weight: float, *, overwrite: bool = False
+        self,
+        other: NodeProtocol,
+        weight: CouplingWeight,
+        *,
+        overwrite: bool = False,
     ) -> None:
-        if isinstance(other, NodoNX):
+        if isinstance(other, NodeNX):
             add_edge(
                 self.G,
                 self.n,
@@ -246,12 +271,10 @@ class NodoNX(NodoProtocol):
         mapping = ensure_node_offset_map(self.G)
         return mapping.get(self.n, 0)
 
-    def all_nodes(self) -> Iterable[NodoProtocol]:
+    def all_nodes(self) -> Iterable[NodeProtocol]:
         override = self.graph.get("_all_nodes")
         if override is not None:
             return override
 
         nodes = cached_node_list(self.G)
-        return tuple(NodoNX.from_graph(self.G, v) for v in nodes)
-
-
+        return tuple(NodeNX.from_graph(self.G, v) for v in nodes)

tnfr/node.pyi

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterable, MutableMapping
+from typing import Any, Callable, Optional, Protocol, SupportsFloat, TypeVar
+
+from .types import (
+    CouplingWeight,
+    DeltaNFR,
+    EPIValue,
+    NodeId,
+    Phase,
+    SecondDerivativeEPI,
+    SenseIndex,
+    StructuralFrequency,
+    TNFRGraph,
+)
+
+T = TypeVar("T")
+
+__all__ = ("NodeNX", "NodeProtocol", "add_edge")
+
+
+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: ...
+
+
+ALIAS_EPI: tuple[str, ...]
+ALIAS_VF: tuple[str, ...]
+ALIAS_THETA: tuple[str, ...]
+ALIAS_SI: tuple[str, ...]
+ALIAS_EPI_KIND: tuple[str, ...]
+ALIAS_DNFR: tuple[str, ...]
+ALIAS_D2EPI: tuple[str, ...]
+
+ATTR_SPECS: dict[str, AttrSpec]
+
+
+def _add_edge_common(
+    n1: NodeId,
+    n2: NodeId,
+    weight: CouplingWeight | SupportsFloat | str,
+) -> Optional[CouplingWeight]: ...
+
+
+def add_edge(
+    graph: TNFRGraph,
+    n1: NodeId,
+    n2: NodeId,
+    weight: CouplingWeight | SupportsFloat | str,
+    overwrite: bool = ...,
+) -> 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 _glyph_storage(self) -> MutableMapping[str, object]: ...
+
+    def has_edge(self, other: NodeProtocol) -> bool: ...
+
+    def add_edge(
+        self,
+        other: NodeProtocol,
+        weight: CouplingWeight,
+        *,
+        overwrite: bool = ...,
+    ) -> None: ...
+
+    def offset(self) -> int: ...
+
+    def all_nodes(self) -> Iterable[NodeProtocol]: ...
+
+
+class NodeNX(NodeProtocol):
+    G: TNFRGraph
+    n: NodeId
+    graph: MutableMapping[str, Any]
+
+    def __init__(self, G: TNFRGraph, n: NodeId) -> None: ...
+
+    @classmethod
+    def from_graph(cls, G: TNFRGraph, n: NodeId) -> "NodeNX": ...
+
+    def _glyph_storage(self) -> MutableMapping[str, Any]: ...
+
+    @property
+    def EPI(self) -> EPIValue: ...
+
+    @EPI.setter
+    def EPI(self, value: EPIValue) -> None: ...
+
+    @property
+    def vf(self) -> StructuralFrequency: ...
+
+    @vf.setter
+    def vf(self, value: StructuralFrequency) -> None: ...
+
+    @property
+    def theta(self) -> Phase: ...
+
+    @theta.setter
+    def theta(self, value: Phase) -> None: ...
+
+    @property
+    def Si(self) -> SenseIndex: ...
+
+    @Si.setter
+    def Si(self, value: SenseIndex) -> None: ...
+
+    @property
+    def epi_kind(self) -> str: ...
+
+    @epi_kind.setter
+    def epi_kind(self, value: str) -> None: ...
+
+    @property
+    def dnfr(self) -> DeltaNFR: ...
+
+    @dnfr.setter
+    def dnfr(self, value: DeltaNFR) -> None: ...
+
+    @property
+    def d2EPI(self) -> SecondDerivativeEPI: ...
+
+    @d2EPI.setter
+    def d2EPI(self, value: SecondDerivativeEPI) -> None: ...
+
+    def neighbors(self) -> Iterable[NodeId]: ...
+
+    def has_edge(self, other: NodeProtocol) -> bool: ...
+
+    def add_edge(
+        self,
+        other: NodeProtocol,
+        weight: CouplingWeight,
+        *,
+        overwrite: bool = ...,
+    ) -> None: ...
+
+    def offset(self) -> int: ...
+
+    def all_nodes(self) -> Iterable[NodeProtocol]: ...
+
+

tnfr/observers.py

@@ -1,12 +1,13 @@
 """Observer management."""
 
 from __future__ import annotations
+
+from collections.abc import Mapping
 from functools import partial
 import statistics
 from statistics import StatisticsError, pvariance
 
-from .constants import get_aliases
-from .alias import get_attr
+from .alias import get_theta_attr
 from .helpers.numeric import angle_diff
 from .callback_utils import CallbackEvent, callback_manager
 from .glyph_history import (
@@ -14,15 +15,17 @@ from .glyph_history import (
     count_glyphs,
     append_metric,
 )
-from .collections_utils import normalize_counter, mix_groups
-from .constants_glyphs import GLYPH_GROUPS
+from .types import Glyph, GlyphLoadDistribution, TNFRGraph
+from .utils import (
+    get_logger,
+    get_numpy,
+    mix_groups,
+    normalize_counter,
+    validate_window,
+)
+from .config.constants 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",
@@ -42,11 +45,10 @@ 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)))
@@ -59,7 +61,7 @@ _STD_CALLBACKS = {
 }
 
 
-def attach_standard_observer(G):
+def attach_standard_observer(G: TNFRGraph) -> TNFRGraph:
     """Register standard callbacks: before_step, after_step, on_remesh."""
     if G.graph.get("_STD_OBSERVER"):
         return G
@@ -69,12 +71,12 @@ def attach_standard_observer(G):
     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,7 +85,11 @@ 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:
     if not _ensure_nodes(G):
         return 1.0
     if R is None or psi is None:
@@ -92,10 +98,11 @@ def phase_sync(G, R: float | None = None, psi: float | None = None) -> float:
             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)
-    )
+    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 +117,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,7 +127,7 @@ def kuramoto_order(
     return float(R)
 
 
-def glyph_load(G, window: int | None = None) -> dict:
+def glyph_load(G: TNFRGraph, window: int | None = None) -> GlyphLoadDistribution:
     """Return distribution of glyphs applied in the network.
 
     - ``window``: if provided, count only the last ``window`` events per node;
@@ -128,21 +135,28 @@ def glyph_load(G, window: int | None = None) -> dict:
     Returns a dict with proportions per glyph 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 +165,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)