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

tnfr/metrics/trig_cache.py

@@ -0,0 +1,109 @@
+"""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_attr
+from ..constants import get_aliases
+from ..cache import edge_version_cache
+from ..import_utils import get_numpy
+from ..types import GraphLike
+
+ALIAS_THETA = get_aliases("THETA")
+
+__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_attr(data, ALIAS_THETA, 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/node.py

@@ -1,202 +1,257 @@
+"""Node utilities and structures for TNFR graphs."""
+
 from __future__ import annotations
-from dataclasses import dataclass, field
-from typing import Deque, Dict, Iterable, List, Optional, Protocol
-from collections import deque
+from typing import Iterable, MutableMapping, Optional, Protocol, TypeVar
+from collections.abc import Hashable
+import math
+
+from .constants import get_aliases
+from .alias import (
+    get_attr,
+    get_attr_str,
+    set_attr,
+    set_attr_str,
+    set_vf,
+    set_dnfr,
+    set_theta,
+)
+from .cache import (
+    cached_node_list,
+    ensure_node_offset_map,
+    increment_edge_version,
+)
+from .graph_utils import 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")
+
+# 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)``.
+    """
+
+    def fget(self) -> T:
+        return to_python(getter(self.G.nodes[self.n], aliases, default))
+
+    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)
 
-from .constants import DEFAULTS
-from .helpers import push_glifo
+    return property(fget, fset)
 
 
-class NodoProtocol(Protocol):
-    """Protocolo mínimo para nodos TNFR."""
+def _add_edge_common(n1, n2, weight) -> Optional[float]:
+    """Validate basic edge constraints.
 
-    EPI: float
-    vf: float
-    theta: float
-    Si: float
-    epi_kind: str
-    dnfr: float
-    d2EPI: float
-    graph: Dict[str, object]
+    Returns the parsed weight if the edge can be added. ``None`` is returned
+    when the edge should be ignored (e.g. self-connections).
+    """
 
-    def neighbors(self) -> Iterable["NodoProtocol"]:
-        ...
+    if n1 == n2:
+        return None
 
-    def push_glifo(self, glifo: str, window: int) -> 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")
 
-    def has_edge(self, other: "NodoProtocol") -> bool:
-        ...
+    return weight
 
-    def add_edge(self, other: "NodoProtocol", weight: float) -> None:
-        ...
 
-    def offset(self) -> int:
-        ...
+def add_edge(
+    graph,
+    n1,
+    n2,
+    weight,
+    overwrite: bool = False,
+):
+    """Add an edge between ``n1`` and ``n2`` in a ``networkx`` graph."""
 
-    def all_nodes(self) -> Iterable["NodoProtocol"]:
-        ...
+    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")
 
-@dataclass
-class NodoTNFR:
-    """Representa un nodo TNFR autónomo."""
+    if graph.has_edge(n1, n2) and not overwrite:
+        return
 
-    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)))
+    graph.add_edge(n1, n2, weight=weight)
+    increment_edge_version(graph)
 
-    def neighbors(self) -> Iterable["NodoTNFR"]:
-        return list(self._neighbors)
 
-    def has_edge(self, other: "NodoTNFR") -> bool:
-        return other in self._neighbors
+class NodoProtocol(Protocol):
+    """Minimal protocol for TNFR nodes."""
 
-    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)
+    EPI: float
+    vf: float
+    theta: float
+    Si: float
+    epi_kind: str
+    dnfr: float
+    d2EPI: float
+    graph: dict[str, object]
 
-    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 neighbors(self) -> Iterable[NodoProtocol | Hashable]: ...
 
-    def offset(self) -> int:
-        return 0
+    def _glyph_storage(self) -> MutableMapping[str, object]: ...
+
+    def has_edge(self, other: "NodoProtocol") -> bool: ...
 
-    def all_nodes(self) -> Iterable["NodoTNFR"]:
-        return list(getattr(self.graph, "_all_nodes", [self]))
+    def add_edge(
+        self, other: "NodoProtocol", weight: float, *, overwrite: bool = False
+    ) -> None: ...
 
-    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 offset(self) -> int: ...
 
-    def integrar(self, dt: float) -> None:
-        self.EPI += self.dnfr * dt
+    def all_nodes(self) -> Iterable["NodoProtocol"]: ...
 
 
 class NodoNX(NodoProtocol):
-    """Adaptador para nodos ``networkx``."""
+    """Adapter for ``networkx`` nodes."""
+
+    # Statically defined property descriptors for ``NodoNX`` 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
-
-    @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
+        G.graph.setdefault("_node_cache", {})[n] = self
+
+    def _glyph_storage(self):
+        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)}")
+        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[Hashable]:
+        """Iterate neighbour identifiers (IDs).
+
+        Wrap each resulting ID with :meth:`from_graph` to obtain the cached
+        ``NodoNX`` instance when actual node objects are required.
+        """
+        return self.G.neighbors(self.n)
 
     def has_edge(self, other: NodoProtocol) -> bool:
         if isinstance(other, NodoNX):
             return self.G.has_edge(self.n, other.n)
         raise NotImplementedError
 
-    def add_edge(self, other: NodoProtocol, weight: float) -> None:
+    def add_edge(
+        self, other: NodoProtocol, weight: float, *, overwrite: bool = False
+    ) -> None:
         if isinstance(other, NodoNX):
-            self.G.add_edge(self.n, other.n, weight=float(weight))
+            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[NodoProtocol]:
-        return [NodoNX(self.G, v) for v in self.G.nodes()]
+        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)
+
+