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

tnfr/metrics/trig_cache.py

@@ -0,0 +1,105 @@
+"""Trigonometric caches for TNFR metrics.
+
+The cosine/sine storage helpers live here to keep :mod:`tnfr.metrics.trig`
+focused on pure mathematical utilities (phase means, compensated sums, etc.).
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping
+
+from ..alias import get_theta_attr
+from ..types import GraphLike
+from ..utils import edge_version_cache, get_numpy
+
+__all__ = ("TrigCache", "compute_theta_trig", "get_trig_cache", "_compute_trig_python")
+
+
+@dataclass(slots=True)
+class TrigCache:
+    """Container for cached trigonometric values per node."""
+
+    cos: dict[Any, float]
+    sin: dict[Any, float]
+    theta: dict[Any, float]
+
+
+def _iter_theta_pairs(
+    nodes: Iterable[tuple[Any, Mapping[str, Any] | float]],
+) -> Iterable[tuple[Any, float]]:
+    """Yield ``(node, θ)`` pairs from ``nodes``."""
+
+    for n, data in nodes:
+        if isinstance(data, Mapping):
+            yield n, get_theta_attr(data, 0.0) or 0.0
+        else:
+            yield n, float(data)
+
+
+def _compute_trig_python(
+    nodes: Iterable[tuple[Any, Mapping[str, Any] | float]],
+) -> TrigCache:
+    """Compute trigonometric mappings using pure Python."""
+
+    cos_th: dict[Any, float] = {}
+    sin_th: dict[Any, float] = {}
+    thetas: dict[Any, float] = {}
+    for n, th in _iter_theta_pairs(nodes):
+        thetas[n] = th
+        cos_th[n] = math.cos(th)
+        sin_th[n] = math.sin(th)
+    return TrigCache(cos=cos_th, sin=sin_th, theta=thetas)
+
+
+def compute_theta_trig(
+    nodes: Iterable[tuple[Any, Mapping[str, Any] | float]],
+    np: Any | None = None,
+) -> TrigCache:
+    """Return trigonometric mappings of ``θ`` per node."""
+
+    if np is None:
+        np = get_numpy()
+    if np is None or not all(hasattr(np, attr) for attr in ("fromiter", "cos", "sin")):
+        return _compute_trig_python(nodes)
+
+    pairs = list(_iter_theta_pairs(nodes))
+    if not pairs:
+        return TrigCache(cos={}, sin={}, theta={})
+
+    node_list, theta_vals = zip(*pairs)
+    theta_arr = np.fromiter(theta_vals, dtype=float)
+    cos_arr = np.cos(theta_arr)
+    sin_arr = np.sin(theta_arr)
+
+    cos_th = dict(zip(node_list, map(float, cos_arr)))
+    sin_th = dict(zip(node_list, map(float, sin_arr)))
+    thetas = dict(zip(node_list, map(float, theta_arr)))
+    return TrigCache(cos=cos_th, sin=sin_th, theta=thetas)
+
+
+def _build_trig_cache(G: GraphLike, np: Any | None = None) -> TrigCache:
+    """Construct trigonometric cache for ``G``."""
+
+    return compute_theta_trig(G.nodes(data=True), np=np)
+
+
+def get_trig_cache(
+    G: GraphLike,
+    *,
+    np: Any | None = None,
+    cache_size: int | None = 128,
+) -> TrigCache:
+    """Return cached cosines and sines of ``θ`` per node."""
+
+    if np is None:
+        np = get_numpy()
+    version = G.graph.setdefault("_trig_version", 0)
+    key = ("_trig", version)
+    return edge_version_cache(
+        G,
+        key,
+        lambda: _build_trig_cache(G, np=np),
+        max_entries=cache_size,
+    )

tnfr/metrics/trig_cache.pyi

@@ -0,0 +1,10 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+TrigCache: Any
+_compute_trig_python: Any
+compute_theta_trig: Any
+get_trig_cache: Any

tnfr/node.py

@@ -1,202 +1,280 @@
-from __future__ import annotations
-from dataclasses import dataclass, field
-from typing import Deque, Dict, Iterable, List, Optional, Protocol
-from collections import deque
-
-from .constants import DEFAULTS
-from .helpers import push_glifo
-
-
-class NodoProtocol(Protocol):
-    """Protocolo mínimo para nodos TNFR."""
+"""Node utilities and structures for TNFR graphs."""
 
-    EPI: float
-    vf: float
-    theta: float
-    Si: float
+from __future__ import annotations
+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,
+    set_vf,
+    set_dnfr,
+    set_theta,
+)
+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 .locking import get_lock
+
+ALIAS_EPI = get_aliases("EPI")
+ALIAS_VF = get_aliases("VF")
+ALIAS_THETA = get_aliases("THETA")
+ALIAS_SI = get_aliases("SI")
+ALIAS_EPI_KIND = get_aliases("EPI_KIND")
+ALIAS_DNFR = get_aliases("DNFR")
+ALIAS_D2EPI = get_aliases("D2EPI")
+
+T = TypeVar("T")
+
+__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.
+    """
+
+    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 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)
+
+
+# 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: 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
+    when the edge should be ignored (e.g. self-connections).
+    """
+
+    if n1 == n2:
+        return None
+
+    weight = float(weight)
+    if not math.isfinite(weight):
+        raise ValueError("Edge weight must be a finite number")
+    if weight < 0:
+        raise ValueError("Edge weight must be non-negative")
+
+    return weight
+
+
+def add_edge(
+    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)
+    if weight is None:
+        return
+
+    if not supports_add_edge(graph):
+        raise TypeError("add_edge only supports networkx graphs")
+
+    if graph.has_edge(n1, n2) and not overwrite:
+        return
+
+    graph.add_edge(n1, n2, weight=weight)
+    increment_edge_version(graph)
+
+
+class NodeProtocol(Protocol):
+    """Minimal protocol for TNFR nodes."""
+
+    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"]:
+    def neighbors(self) -> Iterable[NodeProtocol | Hashable]:
         ...
 
-    def push_glifo(self, glifo: str, window: int) -> None:
+    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) -> None:
+    def add_edge(
+        self,
+        other: NodeProtocol,
+        weight: CouplingWeight,
+        *,
+        overwrite: bool = False,
+    ) -> None:
         ...
 
     def offset(self) -> int:
         ...
 
-    def all_nodes(self) -> Iterable["NodoProtocol"]:
+    def all_nodes(self) -> Iterable[NodeProtocol]:
         ...
 
 
-@dataclass
-class NodoTNFR:
-    """Representa un nodo TNFR autónomo."""
-
-    EPI: float = 0.0
-    vf: float = 0.0
-    theta: float = 0.0
-    Si: float = 0.0
-    epi_kind: str = ""
-    dnfr: float = 0.0
-    d2EPI: float = 0.0
-    graph: Dict[str, object] = field(default_factory=dict)
-    _neighbors: List["NodoTNFR"] = field(default_factory=list)
-    _hist_glifos: Deque[str] = field(default_factory=lambda: deque(maxlen=DEFAULTS.get("GLYPH_HYSTERESIS_WINDOW", 7)))
-
-    def neighbors(self) -> Iterable["NodoTNFR"]:
-        return list(self._neighbors)
-
-    def has_edge(self, other: "NodoTNFR") -> bool:
-        return other in self._neighbors
-
-    def add_edge(self, other: "NodoTNFR", weight: float = 1.0) -> None:
-        if other not in self._neighbors:
-            self._neighbors.append(other)
-            other._neighbors.append(self)
-
-    def push_glifo(self, glifo: str, window: int) -> None:
-        self._hist_glifos.append(glifo)
-        while len(self._hist_glifos) > window:
-            self._hist_glifos.popleft()
-        self.epi_kind = glifo
-
-    def offset(self) -> int:
-        return 0
-
-    def all_nodes(self) -> Iterable["NodoTNFR"]:
-        return list(getattr(self.graph, "_all_nodes", [self]))
-
-    def aplicar_glifo(self, glifo: str, window: Optional[int] = None) -> None:
-        from .operators import aplicar_glifo_obj
-        aplicar_glifo_obj(self, glifo, window=window)
-
-    def integrar(self, dt: float) -> None:
-        self.EPI += self.dnfr * dt
-
-
-class NodoNX(NodoProtocol):
-    """Adaptador para nodos ``networkx``."""
-
-    def __init__(self, G, n):
-        self.G = G
-        self.n = n
-        self.graph = G.graph
-
-    @property
-    def EPI(self) -> float:
-        from .helpers import _get_attr
-        from .constants import ALIAS_EPI
-        return float(_get_attr(self.G.nodes[self.n], ALIAS_EPI, 0.0))
-
-    @EPI.setter
-    def EPI(self, v: float) -> None:
-        from .helpers import _set_attr
-        from .constants import ALIAS_EPI
-        _set_attr(self.G.nodes[self.n], ALIAS_EPI, float(v))
-
-    @property
-    def vf(self) -> float:
-        from .helpers import _get_attr
-        from .constants import ALIAS_VF
-        return float(_get_attr(self.G.nodes[self.n], ALIAS_VF, 0.0))
-
-    @vf.setter
-    def vf(self, v: float) -> None:
-        from .helpers import _set_attr
-        from .constants import ALIAS_VF
-        _set_attr(self.G.nodes[self.n], ALIAS_VF, float(v))
-
-    @property
-    def theta(self) -> float:
-        from .helpers import _get_attr
-        from .constants import ALIAS_THETA
-        return float(_get_attr(self.G.nodes[self.n], ALIAS_THETA, 0.0))
-
-    @theta.setter
-    def theta(self, v: float) -> None:
-        from .helpers import _set_attr
-        from .constants import ALIAS_THETA
-        _set_attr(self.G.nodes[self.n], ALIAS_THETA, float(v))
-
-    @property
-    def Si(self) -> float:
-        from .helpers import _get_attr
-        from .constants import ALIAS_SI
-        return float(_get_attr(self.G.nodes[self.n], ALIAS_SI, 0.0))
-
-    @Si.setter
-    def Si(self, v: float) -> None:
-        from .helpers import _set_attr
-        from .constants import ALIAS_SI
-        _set_attr(self.G.nodes[self.n], ALIAS_SI, float(v))
-
-    @property
-    def epi_kind(self) -> str:
-        from .helpers import _get_attr_str
-        from .constants import ALIAS_EPI_KIND
-        return _get_attr_str(self.G.nodes[self.n], ALIAS_EPI_KIND, "")
-
-    @epi_kind.setter
-    def epi_kind(self, v: str) -> None:
-        from .helpers import _set_attr_str
-        from .constants import ALIAS_EPI_KIND
-        _set_attr_str(self.G.nodes[self.n], ALIAS_EPI_KIND, str(v))
-
-    @property
-    def dnfr(self) -> float:
-        from .helpers import _get_attr
-        from .constants import ALIAS_DNFR
-        return float(_get_attr(self.G.nodes[self.n], ALIAS_DNFR, 0.0))
-
-    @dnfr.setter
-    def dnfr(self, v: float) -> None:
-        from .helpers import _set_attr
-        from .constants import ALIAS_DNFR
-        _set_attr(self.G.nodes[self.n], ALIAS_DNFR, float(v))
-
-    @property
-    def d2EPI(self) -> float:
-        from .helpers import _get_attr
-        from .constants import ALIAS_D2EPI
-        return float(_get_attr(self.G.nodes[self.n], ALIAS_D2EPI, 0.0))
-
-    @d2EPI.setter
-    def d2EPI(self, v: float) -> None:
-        from .helpers import _set_attr
-        from .constants import ALIAS_D2EPI
-        _set_attr(self.G.nodes[self.n], ALIAS_D2EPI, float(v))
-
-    def neighbors(self) -> Iterable[NodoProtocol]:
-        return [NodoNX(self.G, v) for v in self.G.neighbors(self.n)]
-
-    def push_glifo(self, glifo: str, window: int) -> None:
-        push_glifo(self.G.nodes[self.n], glifo, window)
-        self.epi_kind = glifo
-
-    def has_edge(self, other: NodoProtocol) -> bool:
-        if isinstance(other, NodoNX):
+class NodeNX(NodeProtocol):
+    """Adapter for ``networkx`` nodes."""
+
+    # 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: 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) -> MutableMapping[str, Any]:
+        return self.G.nodes[self.n]
+
+    @classmethod
+    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)
+            if node is None:
+                node = cls(G, n)
+            return node
+
+    def neighbors(self) -> Iterable[NodeId]:
+        """Iterate neighbour identifiers (IDs).
+
+        Wrap each resulting ID with :meth:`from_graph` to obtain the cached
+        ``NodeNX`` instance when actual node objects are required.
+        """
+        return self.G.neighbors(self.n)
+
+    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) -> None:
-        if isinstance(other, NodoNX):
-            self.G.add_edge(self.n, other.n, weight=float(weight))
+    def add_edge(
+        self,
+        other: NodeProtocol,
+        weight: CouplingWeight,
+        *,
+        overwrite: bool = False,
+    ) -> None:
+        if isinstance(other, NodeNX):
+            add_edge(
+                self.G,
+                self.n,
+                other.n,
+                weight,
+                overwrite,
+            )
         else:
             raise NotImplementedError
 
     def offset(self) -> int:
-        from .operators import _node_offset
-        return _node_offset(self.G, self.n)
+        mapping = ensure_node_offset_map(self.G)
+        return mapping.get(self.n, 0)
+
+    def all_nodes(self) -> Iterable[NodeProtocol]:
+        override = self.graph.get("_all_nodes")
+        if override is not None:
+            return override
 
-    def all_nodes(self) -> Iterable[NodoProtocol]:
-        return [NodoNX(self.G, v) for v in self.G.nodes()]
+        nodes = cached_node_list(self.G)
+        return tuple(NodeNX.from_graph(self.G, v) for v in nodes)